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