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

OPTIONS

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

EXAMPLES

204       veritysetup --data-blocks=256 format <data_device> <hash_device>
205
206       Calculates and stores verification data on hash_device  for  the  first
207       256  blocks (of block-size).  If hash_device does not exist, it is cre‐
208       ated (as file image).
209
210       veritysetup format <data_device> <hash_device>
211
212       Calculates and stores verification data on hash_device  for  the  whole
213       data_device.
214
215       veritysetup  --data-blocks=256  --hash-offset=1052672  format  <device>
216       <device>
217
218       Verification data (hashes) is stored on the same device as data (start‐
219       ing at hash-offset).  Hash-offset must be greater than number of blocks
220       in data-area.
221
222       veritysetup --data-blocks=256 --hash-offset=1052672 create  test-device
223       <device> <device> <root_hash>
224
225       Activates  the  verity  device named test-device. Options --data-blocks
226       and  --hash-offset  are  the  same  as  in  the  format  command.   The
227       <root_hash> was calculated in format command.
228
229       veritysetup      --data-blocks=256     --hash-offset=1052672     verify
230       <data_device> <hash_device> <root_hash>
231
232       Verifies device without activation (in userspace).
233
234       veritysetup     --fec-device=<fec_device>     --fec-roots=10     format
235       <data_device> <hash_device>
236
237       Calculates and stores verification and encoding data for data_device.
238
239

REPORTING BUGS

241       Report  bugs,  including  ones  in the documentation, on the cryptsetup
242       mailing list at <dm-crypt@saout.de> or in the 'Issues' section on  LUKS
243       website.   Please  attach  the  output  of  the failed command with the
244       --debug option added.
245

AUTHORS

247       The first implementation  of  veritysetup  was  written  by  Chrome  OS
248       authors.
249
250       This  version  is based on verification code written by Mikulas Patocka
251       <mpatocka@redhat.com> and rewritten for  libcryptsetup  by  Milan  Broz
252       <gmazyland@gmail.com>.
253

COPYRIGHT

255       Copyright © 2012-2020 Red Hat, Inc.
256       Copyright © 2012-2020 Milan Broz
257
258       This is free software; see the source for copying conditions.  There is
259       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
260       PURPOSE.
261