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]
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
187       RETURN CODES
188              Veritysetup returns 0 on success and a non-zero value on error.
189
190              Error codes are:
191                  1 wrong parameters
192                  2 no permission
193                  3 out of memory
194                  4 wrong device specified
195                  5 device already exists or device is busy.
196
197

EXAMPLES

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

REPORTING BUGS

236       Report  bugs,  including  ones  in the documentation, on the cryptsetup
237       mailing list at <dm-crypt@saout.de> or in the 'Issues' section on  LUKS
238       website.   Please  attach  the  output  of  the failed command with the
239       --debug option added.
240

AUTHORS

242       The first implementation  of  veritysetup  was  written  by  Chrome  OS
243       authors.
244
245       This  version  is based on verification code written by Mikulas Patocka
246       <mpatocka@redhat.com> and rewritten for  libcryptsetup  by  Milan  Broz
247       <gmazyland@gmail.com>.
248

COPYRIGHT

250       Copyright © 2012-2019 Red Hat, Inc.
251       Copyright © 2012-2019 Milan Broz
252
253       This is free software; see the source for copying conditions.  There is
254       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
255       PURPOSE.
256