Adding upstream version 2:2.3.7.upstream/2%2.3.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 245 insertions, 0 deletions

diff --git a/man/veritysetup.8 b/man/veritysetup.8
new file mode 100644
index 0000000..ccdfe62
--- /dev/null
+++ b/man/veritysetup.8
@@ -0,0 +1,245 @@
+.TH VERITYSETUP "8" "January 2021" "veritysetup" "Maintenance Commands"
+.SH NAME
+veritysetup - manage dm-verity (block level verification) volumes
+.SH SYNOPSIS
+.B veritysetup <options> <action> <action args>
+.SH DESCRIPTION
+.PP
+Veritysetup is used to configure dm-verity managed device-mapper mappings.
+
+Device-mapper verity target provides read-only transparent integrity
+checking of block devices using kernel crypto API.
+
+The dm-verity devices are always read-only.
+
+Veritysetup supports these operations:
+.PP
+\fIformat\fR <data_device> <hash_device>
+.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\-offset option.
+
+Note you need to provide root hash string for device verification
+or activation. Root hash must be trusted.
+
+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-offset,
+\-\-salt, \-\-uuid]
+.PP
+\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-offset, \-\-no-superblock,
+\-\-ignore-corruption or \-\-restart-on-corruption, \-\-panic-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
+\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
+Reports status for the active verity mapping <name>.
+.PP
+\fIdump\fR <hash_device>
+.IP
+Reports parameters of verity device from on-disk stored superblock.
+
+\fB<options>\fR can be [\-\-no-superblock]
+.SH OPTIONS
+.TP
+.B "\-\-verbose, \-v"
+Print more information on command execution.
+.TP
+.B "\-\-debug"
+Run in debug mode with full diagnostic logs. Debug output
+lines are always prefixed by '#'.
+.TP
+.B "\-\-no-superblock"
+Create or use dm-verity without permanent on-disk superblock.
+.TP
+.B "\-\-format=number"
+Specifies the hash version type.
+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.
+(Note kernel supports only page-size as maximum here.)
+.TP
+.B "\-\-hash-block-size=bytes"
+Used block size for the hash device.
+(Note kernel supports only page-size as maximum here.)
+.TP
+.B "\-\-data-blocks=blocks"
+Size of data device used in verification.
+If not specified, the whole device is used.
+.TP
+.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.
+Format is a hexadecimal string.
+.TP
+.B "\-\-uuid=UUID"
+Use the provided UUID for format command instead of generating new one.
+
+The UUID must be provided in standard UUID format,
+e.g. 12345678-1234-1234-1234-123456789abc.
+.TP
+.B "\-\-ignore-corruption", "\-\-restart-on-corruption", "\-\-panic-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 or  \-\-panic-on-corruption the kernel
+is restarted (panicked) 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.
+
+Block sizes for data and hash devices must match.
+Also, if the verity data_device is encrypted the fec_device should be too.
+
+FEC calculation covers data, hash area, and optional foreign metadata stored on the same
+device with the hash tree (additional space after hash area).
+Size of this optional additional area protected by FEC is calculated from image sizes,
+so you must be sure that you use the same images for activation.
+
+If the hash device is in a separate image, metadata covers the whole rest of the image after the hash area.
+
+If hash and FEC device is in the image, metadata ends on the FEC area offset.
+
+.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.
+
+.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>
+or in the 'Issues' section on LUKS website.
+Please attach the output of the failed command with the
+\-\-debug option added.
+.SH AUTHORS
+The first implementation of veritysetup was written by Chrome OS authors.
+
+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-2021 Red Hat, Inc.
+.br
+Copyright \(co 2012-2021 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 \fBhttps://gitlab.com/cryptsetup/cryptsetup\fR
+
+The verity on-disk format specification available at
+\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity\fR