ee471d9f150b731211b6ff09dd91cd760759f227
[chromiumos/third_party/kernel.git] / Documentation / device-mapper / dm-verity.txt
1 dm-verity
2 ==========
3
4 Device-Mapper's "verity" target provides transparent integrity checking of
5 block devices using a cryptographic digest provided by the kernel crypto API.
6 This target is read-only.
7
8 Parameters: <device path> <hash device path> <tree depth> <alg> <parent-hash>
9
10 <device path>
11     This is the device that is going to be integrity checked.  It may be
12     a subset of the full device as specified to dmsetup (start sector and count)
13     It may be specified as a path, like /dev/sdaX, or a device number,
14     <major>:<minor>.
15
16 <hash device path>
17     This is the device that that supplies the dm-bht hash data.  It may be
18     specified similarly to the device path and may be the same device.  If the
19     same device is used, the hash offset should be outside of the dm-verity
20     configured device size.
21
22 <tree depth>
23     The tree depth determines how many levels of hashes are used when building
24     the tree of hashes.  The root of the tree not included and the leaves of
25     the tree are the hashes of the blocks on disk.
26
27 <alg>
28     The cryptographic hash algorithm used for this device.  This should
29     be the name of the algorithm, like "sha1".
30
31 <root hash>
32     The hexadecimal encoding of the cryptographic hash of all of the
33     neighboring nodes at the first level of the tree.  This hash should be
34     trusted as there is no other authenticity beyond this point.
35
36
37 Theory of operation
38 ===================
39
40 dm-verity is meant to be setup as part of a verified boot path.  This
41 may be anything ranging from a boot using tboot or trustedgrub to just
42 booting from a known-good device (like a USB drive or CD).
43
44 When a dm-verity device is configured, it is expected that the caller
45 has been authenticated in some way (cryptographic signatures, etc).
46 After instantiation, all hashes will be verified on-demand during
47 disk access.  If they cannot be verified up to the root node of the
48 tree, the root hash, then the I/O will fail.  This should identify
49 tampering with any data on the device and the hash data.
50
51 Cryptographic hashes are used to assert the integrity of the device on a
52 per-block basis.  This allows for a lightweight hash computation on first read
53 into the page cache.  Block hashes are stored linearly aligned to the nearest
54 block the size of a page.
55
56 For more information on the hashing process, see dm-bht.txt.
57
58
59 Example
60 =======
61
62 Setup a device;
63 [[
64   dmsetup create vroot --table \
65     "0 204800 verity /dev/sda1 /dev/sda2 0 3 sha1 "\
66     "9f74809a2ee7607b16fcc70d9399a4de9725a727"
67 ]]
68
69 A command line tool is available to compute the hash tree and return the
70 root hash value.
71   http://git.chromium.org/cgi-bin/gitweb.cgi?p=dm-verity.git;a=tree