-.TH VERITYSETUP "8" "June 2012" "veritysetup" "Maintenance Commands"
+.TH VERITYSETUP "8" "January 2019" "veritysetup" "Maintenance Commands"
.SH NAME
veritysetup - manage dm-verity (block level verification) volumes
.SH SYNOPSIS
.IP
Calculates and permanently stores hash verification data for data_device.
Hash area can be located on the same device after data if specified
-by \-\-hash\-start option.
+by \-\-hash\-offset option.
Note you need to provide root hash string for device verification
or activation. Root hash must be trusted.
-If data or hash device argument points to regular file, veritysetup
-allocates loopback device. In this case, hash file size must be enough
-to store the hash area.
+The data or hash device argument can be block device or file image.
+If hash device path doesn't exist, it will be created as file.
\fB<options>\fR can be [\-\-hash, \-\-no-superblock, \-\-format,
-\-\-data-block-size, \-\-hash-block-size, \-\-data-blocks, \-\-hash-start,
+\-\-data-block-size, \-\-hash-block-size, \-\-data-blocks, \-\-hash-offset,
\-\-salt, \-\-uuid]
.PP
-\fIcreate\fR <name> <data_device> <hash_device> <root_hash>
+\fIopen\fR <data_device> <name> <hash_device> <root_hash>
+.br
+\fIcreate\fR <name> <data_device> <hash_device> <root_hash> (\fBOBSOLETE syntax\fR)
.IP
Creates a mapping with <name> backed by device <data_device> and using
<hash_device> for in-kernel verification.
The <root_hash> is a hexadecimal string.
-\fB<options>\fR can be [\-\-hash-start, \-\-no-superblock]
+\fB<options>\fR can be [\-\-hash-offset, \-\-no-superblock,
+\-\-ignore-corruption or \-\-restart-on-corruption, \-\-ignore-zero-blocks,
+\-\-check-at-most-once, \-\-root-hash-signature]
If option \-\-no-superblock is used, you have to use as the same options
as in initial format operation.
.PP
-\fIremove\fR <name>
+\fIverify\fR <data_device> <hash_device> <root_hash>
+.IP
+Verifies data on data_device with use of hash blocks stored on hash_device.
+
+This command performs userspace verification, no kernel device is created.
+
+The <root_hash> is a hexadecimal string.
+
+\fB<options>\fR can be [\-\-hash-offset, \-\-no-superblock]
+
+If option \-\-no-superblock is used, you have to use as the same options
+as in initial format operation.
+.PP
+\fIclose\fR <name>
.IP
Removes existing mapping <name>.
+
+For backward compatibility there is \fBremove\fR command alias
+for \fBclose\fR command.
.PP
\fIstatus\fR <name>
.IP
.TP
.B "\-\-format=number"
Specifies the hash version type.
-Format type 0 is original Chrome OS verion. Format type 1 is current version.
+Format type 0 is original Chrome OS version. Format type 1 is current version.
.TP
.B "\-\-data-block-size=bytes"
Used block size for the data device.
Size of data device used in verification.
If not specified, the whole device is used.
.TP
-.B "\-\-hash-start=512-bytes sectors"
+.B "\-\-hash-offset=bytes"
Offset of hash area/superblock on hash_device.
+Value must be aligned to disk sector offset.
.TP
.B "\-\-salt=hex string"
Salt used for format or verification.
The UUID must be provided in standard UUID format,
e.g. 12345678-1234-1234-1234-123456789abc.
.TP
+.B "\-\-ignore-corruption", "\-\-restart-on-corruption"
+Defines what to do if data integrity problem is detected (data corruption).
+
+Without these options kernel fails the IO operation with I/O error.
+With \-\-ignore-corruption option the corruption is only logged.
+With \-\-restart-on-corruption the kernel is restarted immediately.
+(You have to provide way how to avoid restart loops.)
+
+\fBWARNING:\fR Use these options only for very specific cases.
+These options are available since Linux kernel version 4.1.
+.TP
+.B "\-\-ignore-zero-blocks"
+Instruct kernel to not verify blocks that are expected to contain zeroes
+and always directly return zeroes instead.
+
+\fBWARNING:\fR Use this option only in very specific cases.
+This option is available since Linux kernel version 4.5.
+.TP
+.B "\-\-check-at-most-once"
+Instruct kernel to verify blocks only the first time they are read
+from the data device, rather than every time.
+
+\fBWARNING:\fR It provides a reduced level of security because only
+offline tampering of the data device's content will be detected,
+not online tampering.
+This option is available since Linux kernel version 4.17.
+.TP
+.B "\-\-hash=hash"
+Hash algorithm for dm-verity. For default see \-\-help option.
+.TP
.B "\-\-version"
Show the program version.
+.TP
+.B "\-\-fec-device=fec_device"
+Use forward error correction (FEC) to recover from corruption if hash verification fails.
+Use encoding data from the specified device.
+
+The fec device argument can be block device or file image.
+For format, if fec device path doesn't exist, it will be created as file.
+
+Note: block sizes for data and hash devices must match. Also, if the verity data_device is encrypted the fec_device should be too.
+.TP
+.B "\-\-fec-offset=bytes"
+This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding data.
+.TP
+.B "\-\-fec-roots=num"
+Number of generator roots. This equals to the number of parity bytes in the encoding data.
+In RS(M, N) encoding, the number of roots is M-N. M is 255 and M-N is between 2 and 24 (including).
+.TP
+.B "\-\-root-hash-signature=FILE"
+Path to roothash signature file used to verify the root hash (in kernel).
+This feature requires Linux kernel version 5.4 or more recent.
+.TP
.SH RETURN CODES
Veritysetup returns 0 on success and a non-zero value on error.
-Error codes are: 1 wrong parameters, 2 no permission,
-3 out of memory, 4 wrong device specified, 5 device already exists
-or device is busy.
+Error codes are:
+ 1 wrong parameters
+ 2 no permission
+ 3 out of memory
+ 4 wrong device specified
+ 5 device already exists or device is busy.
+
+.SH EXAMPLES
+.B "veritysetup \-\-data-blocks=256 format <data_device> <hash_device>"
+
+Calculates and stores verification data on hash_device for the first 256 blocks (of block-size).
+If hash_device does not exist, it is created (as file image).
+
+.B "veritysetup format <data_device> <hash_device>"
+
+Calculates and stores verification data on hash_device for the whole data_device.
+
+.B "veritysetup \-\-data-blocks=256 \-\-hash-offset=1052672 format <device> <device>"
+
+Verification data (hashes) is stored on the same device as data (starting at hash-offset).
+Hash-offset must be greater than number of blocks in data-area.
+
+.B "veritysetup \-\-data-blocks=256 \-\-hash-offset=1052672 create test-device <device> <device> <root_hash>"
+
+Activates the verity device named test-device. Options \-\-data-blocks and \-\-hash-offset are the same
+as in the format command. The <root_hash> was calculated in format command.
+
+.B "veritysetup \-\-data-blocks=256 \-\-hash-offset=1052672 verify <data_device> <hash_device> <root_hash>"
+
+Verifies device without activation (in userspace).
+
+.B "veritysetup \-\-fec-device=<fec_device> \-\-fec-roots=10 format <data_device> <hash_device>"
+
+Calculates and stores verification and encoding data for data_device.
+
.SH REPORTING BUGS
Report bugs, including ones in the documentation, on
the cryptsetup mailing list at <dm-crypt@saout.de>
This version is based on verification code written by Mikulas Patocka <mpatocka@redhat.com>
and rewritten for libcryptsetup by Milan Broz <gmazyland@gmail.com>.
.SH COPYRIGHT
-Copyright \(co 2012 Red Hat, Inc.
+Copyright \(co 2012-2020 Red Hat, Inc.
+.br
+Copyright \(co 2012-2020 Milan Broz
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH SEE ALSO
-The project website at \fBhttp://code.google.com/p/cryptsetup/\fR
+The project website at \fBhttps://gitlab.com/cryptsetup/cryptsetup\fR
The verity on-disk format specification available at
-\fBhttp://code.google.com/p/cryptsetup/wiki/DMVerity\fR
+\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity\fR
projects / platform / upstream / cryptsetup.git / blobdiff