Commit | Line | Data |
---|---|---|
a4ffc152 MP |
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 | Construction Parameters | |
9 | ======================= | |
18068bdd | 10 | <version> <dev> <hash_dev> |
a4ffc152 MP |
11 | <data_block_size> <hash_block_size> |
12 | <num_data_blocks> <hash_start_block> | |
13 | <algorithm> <digest> <salt> | |
14 | ||
15 | <version> | |
18068bdd | 16 | This is the type of the on-disk hash format. |
a4ffc152 MP |
17 | |
18 | 0 is the original format used in the Chromium OS. | |
18068bdd MB |
19 | The salt is appended when hashing, digests are stored continuously and |
20 | the rest of the block is padded with zeros. | |
a4ffc152 MP |
21 | |
22 | 1 is the current format that should be used for new devices. | |
18068bdd MB |
23 | The salt is prepended when hashing and each digest is |
24 | padded with zeros to the power of two. | |
a4ffc152 MP |
25 | |
26 | <dev> | |
18068bdd | 27 | This is the device containing data, the integrity of which needs to be |
a4ffc152 MP |
28 | checked. It may be specified as a path, like /dev/sdaX, or a device number, |
29 | <major>:<minor>. | |
30 | ||
31 | <hash_dev> | |
18068bdd | 32 | This is the device that supplies the hash tree data. It may be |
a4ffc152 | 33 | specified similarly to the device path and may be the same device. If the |
18068bdd MB |
34 | same device is used, the hash_start should be outside the configured |
35 | dm-verity device. | |
a4ffc152 MP |
36 | |
37 | <data_block_size> | |
18068bdd MB |
38 | The block size on a data device in bytes. |
39 | Each block corresponds to one digest on the hash device. | |
a4ffc152 MP |
40 | |
41 | <hash_block_size> | |
18068bdd | 42 | The size of a hash block in bytes. |
a4ffc152 MP |
43 | |
44 | <num_data_blocks> | |
45 | The number of data blocks on the data device. Additional blocks are | |
46 | inaccessible. You can place hashes to the same partition as data, in this | |
47 | case hashes are placed after <num_data_blocks>. | |
48 | ||
49 | <hash_start_block> | |
50 | This is the offset, in <hash_block_size>-blocks, from the start of hash_dev | |
51 | to the root block of the hash tree. | |
52 | ||
53 | <algorithm> | |
54 | The cryptographic hash algorithm used for this device. This should | |
55 | be the name of the algorithm, like "sha1". | |
56 | ||
57 | <digest> | |
58 | The hexadecimal encoding of the cryptographic hash of the root hash block | |
59 | and the salt. This hash should be trusted as there is no other authenticity | |
60 | beyond this point. | |
61 | ||
62 | <salt> | |
63 | The hexadecimal encoding of the salt value. | |
64 | ||
65 | Theory of operation | |
66 | =================== | |
67 | ||
18068bdd | 68 | dm-verity is meant to be set up as part of a verified boot path. This |
a4ffc152 MP |
69 | may be anything ranging from a boot using tboot or trustedgrub to just |
70 | booting from a known-good device (like a USB drive or CD). | |
71 | ||
72 | When a dm-verity device is configured, it is expected that the caller | |
73 | has been authenticated in some way (cryptographic signatures, etc). | |
74 | After instantiation, all hashes will be verified on-demand during | |
75 | disk access. If they cannot be verified up to the root node of the | |
18068bdd | 76 | tree, the root hash, then the I/O will fail. This should detect |
a4ffc152 MP |
77 | tampering with any data on the device and the hash data. |
78 | ||
79 | Cryptographic hashes are used to assert the integrity of the device on a | |
18068bdd MB |
80 | per-block basis. This allows for a lightweight hash computation on first read |
81 | into the page cache. Block hashes are stored linearly, aligned to the nearest | |
82 | block size. | |
a4ffc152 MP |
83 | |
84 | Hash Tree | |
85 | --------- | |
86 | ||
87 | Each node in the tree is a cryptographic hash. If it is a leaf node, the hash | |
18068bdd MB |
88 | of some data block on disk is calculated. If it is an intermediary node, |
89 | the hash of a number of child nodes is calculated. | |
a4ffc152 MP |
90 | |
91 | Each entry in the tree is a collection of neighboring nodes that fit in one | |
92 | block. The number is determined based on block_size and the size of the | |
93 | selected cryptographic digest algorithm. The hashes are linearly-ordered in | |
94 | this entry and any unaligned trailing space is ignored but included when | |
95 | calculating the parent node. | |
96 | ||
97 | The tree looks something like: | |
98 | ||
99 | alg = sha256, num_blocks = 32768, block_size = 4096 | |
100 | ||
101 | [ root ] | |
102 | / . . . \ | |
103 | [entry_0] [entry_1] | |
104 | / . . . \ . . . \ | |
105 | [entry_0_0] . . . [entry_0_127] . . . . [entry_1_127] | |
106 | / ... \ / . . . \ / \ | |
107 | blk_0 ... blk_127 blk_16256 blk_16383 blk_32640 . . . blk_32767 | |
108 | ||
109 | ||
110 | On-disk format | |
111 | ============== | |
112 | ||
18068bdd MB |
113 | The verity kernel code does not read the verity metadata on-disk header. |
114 | It only reads the hash blocks which directly follow the header. | |
115 | It is expected that a user-space tool will verify the integrity of the | |
116 | verity header. | |
a4ffc152 | 117 | |
18068bdd MB |
118 | Alternatively, the header can be omitted and the dmsetup parameters can |
119 | be passed via the kernel command-line in a rooted chain of trust where | |
120 | the command-line is verified. | |
a4ffc152 MP |
121 | |
122 | Directly following the header (and with sector number padded to the next hash | |
123 | block boundary) are the hash blocks which are stored a depth at a time | |
124 | (starting from the root), sorted in order of increasing index. | |
125 | ||
18068bdd MB |
126 | The full specification of kernel parameters and on-disk metadata format |
127 | is available at the cryptsetup project's wiki page | |
128 | http://code.google.com/p/cryptsetup/wiki/DMVerity | |
129 | ||
a4ffc152 MP |
130 | Status |
131 | ====== | |
132 | V (for Valid) is returned if every check performed so far was valid. | |
133 | If any check failed, C (for Corruption) is returned. | |
134 | ||
135 | Example | |
136 | ======= | |
18068bdd MB |
137 | Set up a device: |
138 | # dmsetup create vroot --readonly --table \ | |
139 | "0 2097152 verity 1 /dev/sda1 /dev/sda2 4096 4096 262144 1 sha256 "\ | |
a4ffc152 MP |
140 | "4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 "\ |
141 | "1234000000000000000000000000000000000000000000000000000000000000" | |
142 | ||
143 | A command line tool veritysetup is available to compute or verify | |
18068bdd MB |
144 | the hash tree or activate the kernel device. This is available from |
145 | the cryptsetup upstream repository http://code.google.com/p/cryptsetup/ | |
146 | (as a libcryptsetup extension). | |
147 | ||
148 | Create hash on the device: | |
149 | # veritysetup format /dev/sda1 /dev/sda2 | |
150 | ... | |
151 | Root hash: 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 | |
152 | ||
153 | Activate the device: | |
154 | # veritysetup create vroot /dev/sda1 /dev/sda2 \ | |
155 | 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 |