1 =========
2 dm-verity
3 =========
4
5 Device-Mapper's "verity" target provides trans
6 block devices using a cryptographic digest pro
7 This target is read-only.
8
9 Construction Parameters
10 =======================
11
12 ::
13
14 <version> <dev> <hash_dev>
15 <data_block_size> <hash_block_size>
16 <num_data_blocks> <hash_start_block>
17 <algorithm> <digest> <salt>
18 [<#opt_params> <opt_params>]
19
20 <version>
21 This is the type of the on-disk hash forma
22
23 0 is the original format used in the Chrom
24 The salt is appended when hashing, diges
25 the rest of the block is padded with zer
26
27 1 is the current format that should be use
28 The salt is prepended when hashing and e
29 padded with zeroes to the power of two.
30
31 <dev>
32 This is the device containing data, the in
33 checked. It may be specified as a path, l
34 <major>:<minor>.
35
36 <hash_dev>
37 This is the device that supplies the hash
38 specified similarly to the device path and
39 same device is used, the hash_start should
40 dm-verity device.
41
42 <data_block_size>
43 The block size on a data device in bytes.
44 Each block corresponds to one digest on th
45
46 <hash_block_size>
47 The size of a hash block in bytes.
48
49 <num_data_blocks>
50 The number of data blocks on the data devi
51 inaccessible. You can place hashes to the
52 case hashes are placed after <num_data_blo
53
54 <hash_start_block>
55 This is the offset, in <hash_block_size>-b
56 to the root block of the hash tree.
57
58 <algorithm>
59 The cryptographic hash algorithm used for
60 be the name of the algorithm, like "sha1".
61
62 <digest>
63 The hexadecimal encoding of the cryptograp
64 and the salt. This hash should be trusted
65 beyond this point.
66
67 <salt>
68 The hexadecimal encoding of the salt value
69
70 <#opt_params>
71 Number of optional parameters. If there ar
72 the optional parameters section can be ski
73 Otherwise #opt_params is the number of fol
74
75 Example of optional parameters section:
76 1 ignore_corruption
77
78 ignore_corruption
79 Log corrupted blocks, but allow read opera
80
81 restart_on_corruption
82 Restart the system when a corrupted block
83 not compatible with ignore_corruption and
84 avoid restart loops.
85
86 panic_on_corruption
87 Panic the device when a corrupted block is
88 not compatible with ignore_corruption and
89
90 ignore_zero_blocks
91 Do not verify blocks that are expected to
92 zeroes instead. This may be useful if the
93 that are not guaranteed to contain zeroes.
94
95 use_fec_from_device <fec_dev>
96 Use forward error correction (FEC) to reco
97 verification fails. Use encoding data from
98 may be the same device where data and hash
99 fec_start must be outside data and hash ar
100
101 If the encoding data covers additional met
102 on the hash device after the hash blocks.
103
104 Note: block sizes for data and hash device
105 verity <dev> is encrypted the <fec_dev> sh
106
107 fec_roots <num>
108 Number of generator roots. This equals to
109 the encoding data. For example, in RS(M, N
110 is M-N.
111
112 fec_blocks <num>
113 The number of encoding data blocks on the
114 the FEC device is <data_block_size>.
115
116 fec_start <offset>
117 This is the offset, in <data_block_size> b
118 FEC device to the beginning of the encodin
119
120 check_at_most_once
121 Verify data blocks only the first time the
122 rather than every time. This reduces the
123 can be used on systems that are memory and
124 provides a reduced level of security becau
125 data device's content will be detected, no
126
127 Hash blocks are still verified each time t
128 since verification of hash blocks is less
129 blocks, and a hash block will not be verif
130 blocks it covers have been verified anyway
131
132 root_hash_sig_key_desc <key_description>
133 This is the description of the USER_KEY th
134 the pkcs7 signature of the roothash. The p
135 the root hash during the creation of the d
136 Verification of roothash depends on the co
137 being set in the kernel. The signatures a
138 trusted keyring by default, or the seconda
139 DM_VERITY_VERIFY_ROOTHASH_SIG_SECONDARY_KE
140 trusted keyring includes by default the bu
141 also gain new certificates at run time if
142 already in the secondary trusted keyring.
143
144 try_verify_in_tasklet
145 If verity hashes are in cache, verify data
146 of workqueue. This option can reduce IO la
147
148 Theory of operation
149 ===================
150
151 dm-verity is meant to be set up as part of a v
152 may be anything ranging from a boot using tboo
153 booting from a known-good device (like a USB d
154
155 When a dm-verity device is configured, it is e
156 has been authenticated in some way (cryptograp
157 After instantiation, all hashes will be verifi
158 disk access. If they cannot be verified up to
159 tree, the root hash, then the I/O will fail.
160 tampering with any data on the device and the
161
162 Cryptographic hashes are used to assert the in
163 per-block basis. This allows for a lightweight
164 into the page cache. Block hashes are stored l
165 block size.
166
167 If forward error correction (FEC) support is e
168 corrupted data will be verified using the cryp
169 corresponding data. This is why combining erro
170 integrity checking is essential.
171
172 Hash Tree
173 ---------
174
175 Each node in the tree is a cryptographic hash.
176 of some data block on disk is calculated. If i
177 the hash of a number of child nodes is calcula
178
179 Each entry in the tree is a collection of neig
180 block. The number is determined based on bloc
181 selected cryptographic digest algorithm. The
182 this entry and any unaligned trailing space is
183 calculating the parent node.
184
185 The tree looks something like:
186
187 alg = sha256, num_blocks = 32768, bloc
188
189 ::
190
191 [ root ]
192 / . . .
193 [entry_0]
194 / . . . \
195 [entry_0_0] . . . [entry_0_127]
196 / ... \ / . . . \
197 blk_0 ... blk_127 blk_16256 blk_16383
198
199
200 On-disk format
201 ==============
202
203 The verity kernel code does not read the verit
204 It only reads the hash blocks which directly f
205 It is expected that a user-space tool will ver
206 verity header.
207
208 Alternatively, the header can be omitted and t
209 be passed via the kernel command-line in a roo
210 the command-line is verified.
211
212 Directly following the header (and with sector
213 block boundary) are the hash blocks which are
214 (starting from the root), sorted in order of i
215
216 The full specification of kernel parameters an
217 is available at the cryptsetup project's wiki
218
219 https://gitlab.com/cryptsetup/cryptsetup/wik
220
221 Status
222 ======
223 V (for Valid) is returned if every check perfo
224 If any check failed, C (for Corruption) is ret
225
226 Example
227 =======
228 Set up a device::
229
230 # dmsetup create vroot --readonly --table \
231 "0 2097152 verity 1 /dev/sda1 /dev/sda2 40
232 "4392712ba01368efdf14b05c76f9e4df0d5366463
233 "12340000000000000000000000000000000000000
234
235 A command line tool veritysetup is available t
236 the hash tree or activate the kernel device. T
237 the cryptsetup upstream repository https://git
238 (as a libcryptsetup extension).
239
240 Create hash on the device::
241
242 # veritysetup format /dev/sda1 /dev/sda2
243 ...
244 Root hash: 4392712ba01368efdf14b05c76f9e4df0
245
246 Activate the device::
247
248 # veritysetup create vroot /dev/sda1 /dev/sd
249 4392712ba01368efdf14b05c76f9e4df0d53664630
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.