veritysetup(8)

1VERITYSETUP(8)               Maintenance Commands               VERITYSETUP(8)
2
3
4

NAME

6       veritysetup - manage dm-verity (block level verification) volumes
7

SYNOPSIS

9       veritysetup <options> <action> <action args>
10

DESCRIPTION

12       Veritysetup  is  used to configure dm-verity managed device-mapper map‐
13       pings.
14
15       Device-mapper verity target provides  read-only  transparent  integrity
16       checking of block devices using kernel crypto API.
17
18       The dm-verity devices are always read-only.
19
20       Veritysetup supports these operations:
21
22       format <data_device> <hash_device>
23
24              Calculates  and  permanently  stores  hash verification data for
25              data_device.  Hash area can be located on the same device  after
26              data if specified by --hash-offset option.
27
28              Note  you  need to provide root hash string for device verifica‐
29              tion or activation. Root hash must be trusted.
30
31              The data or hash device argument can be block device or file im‐
32              age.   If  hash device path doesn't exist, it will be created as
33              file.
34
35              <options> can be  [--hash,  --no-superblock,  --format,  --data-
36              block-size,   --hash-block-size,  --data-blocks,  --hash-offset,
37              --salt, --uuid, --root-hash-file]
38
39              If option --root-hash-file is used, the root hash is  stored  in
40              hex-encoded text format in <path>.
41
42       open <data_device> <name> <hash_device> <root_hash>
43       open <data_device> <name> <hash_device> --root-hash-file <path>
44       create  <name>  <data_device> <hash_device> <root_hash>  (OBSOLETE syn‐
45       tax)
46
47              Creates a mapping with <name> backed by device <data_device> and
48              using <hash_device> for in-kernel verification.
49
50              The <root_hash> is a hexadecimal string.
51
52              <options>  can be [--hash-offset, --no-superblock, --ignore-cor‐
53              ruption or --restart-on-corruption, --panic-on-corruption, --ig‐
54              nore-zero-blocks,  --check-at-most-once,  --root-hash-signature,
55              --root-hash-file]
56
57              If option --root-hash-file is used, the root hash is  read  from
58              <path>  instead of from the command line parameter. Expects hex-
59              encoded text, without terminating newline.
60
61              If option --no-superblock is used, you have to use as  the  same
62              options as in initial format operation.
63
64       verify <data_device> <hash_device> <root_hash>
65       verify <data_device> <hash_device> --root-hash-file <path>
66
67              Verifies  data  on data_device with use of hash blocks stored on
68              hash_device.
69
70              This command performs userspace verification, no  kernel  device
71              is created.
72
73              The <root_hash> is a hexadecimal string.
74
75              If  option  --root-hash-file is used, the root hash is read from
76              <path> instead of from the command line parameter. Expects  hex-
77              encoded text, without terminating newline.
78
79              <options>  can  be [--hash-offset, --no-superblock, --root-hash-
80              file]
81
82              If option --no-superblock is used, you have to use as  the  same
83              options as in initial format operation.
84
85       close <name>
86
87              Removes existing mapping <name>.
88
89              For  backward  compatibility  there  is remove command alias for
90              close command.
91
92              <options> can be [--deferred] or [--cancel-deferred]
93
94
95       status <name>
96
97              Reports status for the active verity mapping <name>.
98
99       dump <hash_device>
100
101              Reports parameters of verity  device  from  on-disk  stored  su‐
102              perblock.
103
104              <options> can be [--hash-offset]
105

OPTIONS

107       --verbose, -v
108              Print more information on command execution.
109
110       --debug
111              Run  in debug mode with full diagnostic logs. Debug output lines
112              are always prefixed by '#'.
113
114       --no-superblock
115              Create or use dm-verity without permanent on-disk superblock.
116
117       --format=number
118              Specifies the hash version type.   Format  type  0  is  original
119              Chrome OS version. Format type 1 is current version.
120
121       --data-block-size=bytes
122              Used block size for the data device.  (Note kernel supports only
123              page-size as maximum here.)
124
125       --hash-block-size=bytes
126              Used block size for the hash device.  (Note kernel supports only
127              page-size as maximum here.)
128
129       --data-blocks=blocks
130              Size of data device used in verification.  If not specified, the
131              whole device is used.
132
133       --hash-offset=bytes
134              Offset of hash area/superblock on hash_device.   Value  must  be
135              aligned to disk sector offset.
136
137       --salt=hex string
138              Salt  used  for format or verification.  Format is a hexadecimal
139              string.
140
141       --uuid=UUID
142              Use the provided UUID for format command instead  of  generating
143              new one.
144
145              The  UUID  must  be  provided  in  standard  UUID  format,  e.g.
146              12345678-1234-1234-1234-123456789abc.
147
148       --ignore-corruption , --restart-on-corruption , --panic-on-corruption
149              Defines what to do if data integrity problem is  detected  (data
150              corruption).
151
152              Without these options kernel fails the IO operation with I/O er‐
153              ror.  With --ignore-corruption option  the  corruption  is  only
154              logged.   With --restart-on-corruption or  --panic-on-corruption
155              the kernel is restarted (panicked) immediately.   (You  have  to
156              provide way how to avoid restart loops.)
157
158              WARNING:  Use these options only for very specific cases.  These
159              options are available since Linux kernel version 4.1.
160
161       --ignore-zero-blocks
162              Instruct kernel to not verify blocks that are expected  to  con‐
163              tain zeroes and always directly return zeroes instead.
164
165              WARNING:  Use this option only in very specific cases.  This op‐
166              tion is available since Linux kernel version 4.5.
167
168       --check-at-most-once
169              Instruct kernel to verify blocks only the first  time  they  are
170              read from the data device, rather than every time.
171
172              WARNING:  It  provides  a reduced level of security because only
173              offline tampering of the data device's content will be detected,
174              not online tampering.  This option is available since Linux ker‐
175              nel version 4.17.
176
177       --hash=hash
178              Hash algorithm for dm-verity. For default see --help option.
179
180       --version
181              Show the program version.
182
183       --fec-device=fec_device
184              Use forward error correction (FEC) to recover from corruption if
185              hash  verification  fails.  Use encoding data from the specified
186              device.
187
188              The fec device argument can be block device or file image.   For
189              format,  if fec device path doesn't exist, it will be created as
190              file.
191
192              Block sizes for data and hash devices must match.  Also, if  the
193              verity data_device is encrypted the fec_device should be too.
194
195              FEC  calculation  covers  data,  hash area, and optional foreign
196              metadata stored on the same device with  the  hash  tree  (addi‐
197              tional space after hash area).  Size of this optional additional
198              area protected by FEC is calculated from  image  sizes,  so  you
199              must be sure that you use the same images for activation.
200
201              If  the  hash device is in a separate image, metadata covers the
202              whole rest of the image after the hash area.
203
204              If hash and FEC device is in the image, metadata ends on the FEC
205              area offset.
206
207
208       --fec-offset=bytes
209              This  is  the offset, in bytes, from the start of the FEC device
210              to the beginning of the encoding data.
211
212       --fec-roots=num
213              Number of generator roots. This equals to the number  of  parity
214              bytes in the encoding data.  In RS(M, N) encoding, the number of
215              roots is M-N. M is 255 and M-N is between 2 and 24 (including).
216
217       --root-hash-file=FILE
218              Path to file with stored root hash in hex-encoded text.
219
220       --root-hash-signature=FILE
221              Path to roothash signature file used to verify the root hash (in
222              kernel).  This feature requires Linux kernel version 5.4 or more
223              recent.
224
225       --deferred
226              Defers device removal in  close  command  until  the  last  user
227              closes it.
228
229       --cancel-deferred
230              Removes a previously configured deferred device removal in close
231              command.
232
233
234       RETURN CODES
235              Veritysetup returns 0 on success and a non-zero value on error.
236
237              Error codes are:
238                  1 wrong parameters
239                  2 no permission
240                  3 out of memory
241                  4 wrong device specified
242                  5 device already exists or device is busy.
243
244

EXAMPLES

246       veritysetup --data-blocks=256 format <data_device> <hash_device>
247
248       Calculates and stores verification data on hash_device  for  the  first
249       256  blocks (of block-size).  If hash_device does not exist, it is cre‐
250       ated (as file image).
251
252       veritysetup format --root-hash-file <path> <data_device> <hash_device>
253
254       Calculates and stores verification data on hash_device  for  the  whole
255       data_device, and store the root hash as hex-encoded text in <path>.
256
257       veritysetup  --data-blocks=256  --hash-offset=1052672  format  <device>
258       <device>
259
260       Verification data (hashes) is stored on the same device as data (start‐
261       ing at hash-offset).  Hash-offset must be greater than number of blocks
262       in data-area.
263
264       veritysetup --data-blocks=256 --hash-offset=1052672 create  test-device
265       <device> <device> <root_hash>
266
267       Activates  the  verity  device named test-device. Options --data-blocks
268       and  --hash-offset  are  the  same  as  in  the  format  command.   The
269       <root_hash> was calculated in format command.
270
271       veritysetup  --data-blocks=256  --hash-offset=1052672  verify <data_de‐
272       vice> <hash_device> <root_hash>
273
274       Verifies device without activation (in userspace).
275
276       veritysetup  --data-blocks=256  --hash-offset=1052672  --root-hash-file
277       <path> verify <data_device> <hash_device>
278
279       Verifies device without activation (in userspace). Root hash passed via
280       a file rather than inline.
281
282       veritysetup --fec-device=<fec_device> --fec-roots=10  format  <data_de‐
283       vice> <hash_device>
284
285       Calculates and stores verification and encoding data for data_device.
286
287

REPORTING BUGS

289       Report  bugs,  including  ones  in the documentation, on the cryptsetup
290       mailing list at <dm-crypt@saout.de> or in the 'Issues' section on  LUKS
291       website.  Please attach the output of the failed command with the --de‐
292       bug option added.
293

AUTHORS

295       The first implementation of veritysetup was written by  Chrome  OS  au‐
296       thors.
297
298       This  version  is based on verification code written by Mikulas Patocka
299       <mpatocka@redhat.com> and rewritten for  libcryptsetup  by  Milan  Broz
300       <gmazyland@gmail.com>.
301

COPYRIGHT

303       Copyright © 2012-2021 Red Hat, Inc.
304       Copyright © 2012-2021 Milan Broz
305
306       This is free software; see the source for copying conditions.  There is
307       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
308       PURPOSE.
309