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
32              image.  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]
38
39       open <data_device> <name> <hash_device> <root_hash>
40       create <name> <data_device> <hash_device> <root_hash>   (OBSOLETE  syn‐
41       tax)
42
43              Creates a mapping with <name> backed by device <data_device> and
44              using <hash_device> for in-kernel verification.
45
46              The <root_hash> is a hexadecimal string.
47
48              <options> can be [--hash-offset, --no-superblock,  --ignore-cor‐
49              ruption   or   --restart-on-corruption,   --panic-on-corruption,
50              --ignore-zero-blocks,  --check-at-most-once,  --root-hash-signa‐
51              ture]
52
53              If  option  --no-superblock is used, you have to use as the same
54              options as in initial format operation.
55
56       verify <data_device> <hash_device> <root_hash>
57
58              Verifies data on data_device with use of hash blocks  stored  on
59              hash_device.
60
61              This  command  performs userspace verification, no kernel device
62              is created.
63
64              The <root_hash> is a hexadecimal string.
65
66              <options> can be [--hash-offset, --no-superblock]
67
68              If option --no-superblock is used, you have to use as  the  same
69              options as in initial format operation.
70
71       close <name>
72
73              Removes existing mapping <name>.
74
75              For  backward  compatibility  there  is remove command alias for
76              close command.
77
78       status <name>
79
80              Reports status for the active verity mapping <name>.
81
82       dump <hash_device>
83
84              Reports  parameters  of  verity  device  from   on-disk   stored
85              superblock.
86
87              <options> can be [--no-superblock]
88

OPTIONS

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

EXAMPLES

218       veritysetup --data-blocks=256 format <data_device> <hash_device>
219
220       Calculates and stores verification data on hash_device  for  the  first
221       256  blocks (of block-size).  If hash_device does not exist, it is cre‐
222       ated (as file image).
223
224       veritysetup format <data_device> <hash_device>
225
226       Calculates and stores verification data on hash_device  for  the  whole
227       data_device.
228
229       veritysetup  --data-blocks=256  --hash-offset=1052672  format  <device>
230       <device>
231
232       Verification data (hashes) is stored on the same device as data (start‐
233       ing at hash-offset).  Hash-offset must be greater than number of blocks
234       in data-area.
235
236       veritysetup --data-blocks=256 --hash-offset=1052672 create  test-device
237       <device> <device> <root_hash>
238
239       Activates  the  verity  device named test-device. Options --data-blocks
240       and  --hash-offset  are  the  same  as  in  the  format  command.   The
241       <root_hash> was calculated in format command.
242
243       veritysetup      --data-blocks=256     --hash-offset=1052672     verify
244       <data_device> <hash_device> <root_hash>
245
246       Verifies device without activation (in userspace).
247
248       veritysetup     --fec-device=<fec_device>     --fec-roots=10     format
249       <data_device> <hash_device>
250
251       Calculates and stores verification and encoding data for data_device.
252
253

REPORTING BUGS

255       Report  bugs,  including  ones  in the documentation, on the cryptsetup
256       mailing list at <dm-crypt@saout.de> or in the 'Issues' section on  LUKS
257       website.   Please  attach  the  output  of  the failed command with the
258       --debug option added.
259

AUTHORS

261       The first implementation  of  veritysetup  was  written  by  Chrome  OS
262       authors.
263
264       This  version  is based on verification code written by Mikulas Patocka
265       <mpatocka@redhat.com> and rewritten for  libcryptsetup  by  Milan  Broz
266       <gmazyland@gmail.com>.
267

COPYRIGHT

269       Copyright © 2012-2021 Red Hat, Inc.
270       Copyright © 2012-2021 Milan Broz
271
272       This is free software; see the source for copying conditions.  There is
273       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
274       PURPOSE.
275