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

NAME

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

SYNOPSIS

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

DESCRIPTION

12       Veritysetup is used to configure dm-verity managed device-mapper
13       mappings.
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

BASIC ACTIONS

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

OPTIONS

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

RETURN CODES

243       Veritysetup returns 0 on success and a non-zero value on error.
244
245       Error codes are: 1 wrong parameters, 2 no permission, 3 out of memory,
246       4 wrong device specified, 5 device already exists or device is busy.
247

EXAMPLES

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

DM-VERITY ON-DISK SPECIFICATION

291       The on-disk format specification is available at DMVerity
292       <https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity> page.
293

AUTHORS

295       The first implementation of veritysetup was written by Chrome OS
296       authors.
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

REPORTING BUGS

303       Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or
304       in Issues project section
305       <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.
306
307       Please attach output of the failed command with --debug option added.
308

SEE ALSO

310       Cryptsetup FAQ
311       <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
312
313       cryptsetup(8), integritysetup(8) and veritysetup(8)
314

CRYPTSETUP

316       Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
317
318
319
320veritysetup 2.5.0                 2022-07-28                    VERITYSETUP(8)
Impressum