diff options
Diffstat (limited to 'man/veritysetup.8')
| -rw-r--r-- | man/veritysetup.8 | 245 |
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 |