"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "man/veritysetup.8" between
cryptsetup-2.3.6.tar.xz and cryptsetup-2.4.0.tar.xz

About: cryptsetup is a utility used to conveniently setup disk encryption based on the dm-crypt kernel module. These include plain dm-crypt volumes, LUKS volumes, loop-AES and TrueCrypt compatible format.

veritysetup.8  (cryptsetup-2.3.6.tar.xz):veritysetup.8  (cryptsetup-2.4.0.tar.xz)
skipping to change at line 31 skipping to change at line 31
Calculates and permanently stores hash verification data for da ta_device. Hash area can be Calculates and permanently stores hash verification data for da ta_device. Hash area can be
located on the same device after data if specified by --hash-offse t option. located on the same device after data if specified by --hash-offse t option.
Note you need to provide root hash string for device verification or activation. Root hash must be Note you need to provide root hash string for device verification or activation. Root hash must be
trusted. trusted.
The data or hash device argument can be block device or file image . If hash device path doesn't 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. exist, it will be created as file.
<options> can be [--hash, --no-superblock, --format, --data-block- size, --hash-block-size, --data- <options> can be [--hash, --no-superblock, --format, --data-block- size, --hash-block-size, --data-
blocks, --hash-offset, --salt, --uuid] blocks, --hash-offset, --salt, --uuid, --root-hash-file]
If option --root-hash-file is used, the root hash is stored in hex
-encoded text format in <path>.
open <data_device> <name> <hash_device> <root_hash> open <data_device> <name> <hash_device> <root_hash>
open <data_device> <name> <hash_device> --root-hash-file <path>
create <name> <data_device> <hash_device> <root_hash> (OBSOLETE syntax) create <name> <data_device> <hash_device> <root_hash> (OBSOLETE syntax)
Creates a mapping with <name> backed by device <data_device> and u sing <hash_device> for in-kernel Creates a mapping with <name> backed by device <data_device> and u sing <hash_device> for in-kernel
verification. verification.
The <root_hash> is a hexadecimal string. The <root_hash> is a hexadecimal string.
<options> can be [--hash-offset, --no-superblock, --ignore-corrup tion or --restart-on-corruption, <options> can be [--hash-offset, --no-superblock, --ignore-corrup tion or --restart-on-corruption,
--panic-on-corruption, --ignore-zero-blocks, --check-at-most-once, --panic-on-corruption, --ignore-zero-blocks, --check-at-most-once,
--root-hash-signature] --root-hash-signature, --root-
hash-file]
If option --root-hash-file is used, the root hash is read from <p
ath> instead of from the command
line parameter. Expects hex-encoded text, without terminating newl
ine.
If option --no-superblock is used, you have to use as the same opt ions as in initial format opera- If option --no-superblock is used, you have to use as the same opt ions as in initial format opera-
tion. tion.
verify <data_device> <hash_device> <root_hash> verify <data_device> <hash_device> <root_hash>
verify <data_device> <hash_device> --root-hash-file <path>
Verifies data on data_device with use of hash blocks stored on has h_device. Verifies data on data_device with use of hash blocks stored on has h_device.
This command performs userspace verification, no kernel device is created. This command performs userspace verification, no kernel device is created.
The <root_hash> is a hexadecimal string. The <root_hash> is a hexadecimal string.
<options> can be [--hash-offset, --no-superblock] If option --root-hash-file is used, the root hash is read from <p
ath> instead of from the command
line parameter. Expects hex-encoded text, without terminating newl
ine.
<options> can be [--hash-offset, --no-superblock, --root-hash-file
]
If option --no-superblock is used, you have to use as the same opt ions as in initial format opera- If option --no-superblock is used, you have to use as the same opt ions as in initial format opera-
tion. tion.
close <name> close <name>
Removes existing mapping <name>. Removes existing mapping <name>.
For backward compatibility there is remove command alias for close command. For backward compatibility there is remove command alias for close command.
<options> can be [--deferred] or [--cancel-deferred]
status <name> status <name>
Reports status for the active verity mapping <name>. Reports status for the active verity mapping <name>.
dump <hash_device> dump <hash_device>
Reports parameters of verity device from on-disk stored superblock . Reports parameters of verity device from on-disk stored superblock .
<options> can be [--no-superblock] <options> can be [--hash-offset]
OPTIONS OPTIONS
--verbose, -v --verbose, -v
Print more information on command execution. Print more information on command execution.
--debug --debug
Run in debug mode with full diagnostic logs. Debug output lines ar e always prefixed by '#'. Run in debug mode with full diagnostic logs. Debug output lines ar e always prefixed by '#'.
--no-superblock --no-superblock
Create or use dm-verity without permanent on-disk superblock. Create or use dm-verity without permanent on-disk superblock.
--format=number --format=number
Specifies the hash version type. Format type 0 is original Chrome OS version. Format type 1 is Specifies the hash version type. Format type 0 is original Chr ome OS version. Format type 1 is
current version. current version.
--data-block-size=bytes --data-block-size=bytes
Used block size for the data device. (Note kernel supports only p age-size as maximum here.) Used block size for the data device. (Note kernel supports only p age-size as maximum here.)
--hash-block-size=bytes --hash-block-size=bytes
Used block size for the hash device. (Note kernel supports only p age-size as maximum here.) Used block size for the hash device. (Note kernel supports only p age-size as maximum here.)
--data-blocks=blocks --data-blocks=blocks
Size of data device used in verification. If not specified, the w hole device is used. Size of data device used in verification. If not specified, the w hole device is used.
skipping to change at line 113 skipping to change at line 126
Salt used for format or verification. Format is a hexadecimal str ing. Salt used for format or verification. Format is a hexadecimal str ing.
--uuid=UUID --uuid=UUID
Use the provided UUID for format command instead of generating new one. Use the provided UUID for format command instead of generating new one.
The UUID must be provided in standard UUID format, e.g. 12345678-1 234-1234-1234-123456789abc. The UUID must be provided in standard UUID format, e.g. 12345678-1 234-1234-1234-123456789abc.
--ignore-corruption , --restart-on-corruption , --panic-on-corruption --ignore-corruption , --restart-on-corruption , --panic-on-corruption
Defines what to do if data integrity problem is detected (data cor ruption). Defines what to do if data integrity problem is detected (data cor ruption).
Without these options kernel fails the IO operation with I/O Without these options kernel fails the IO operation with I/O er
error. With --ignore-corruption ror. With --ignore-corruption
option the corruption is only logged. With --restart-on-corruptio option the corruption is only logged. With --restart-on-corrupti
n or --panic-on-corruption the on or --panic-on-corruption the
kernel is restarted (panicked) immediately. (You have to provide way how to avoid restart loops.) kernel is restarted (panicked) immediately. (You have to provide way how to avoid restart loops.)
WARNING: Use these options only for very specific cases. These o ptions are available since Linux WARNING: Use these options only for very specific cases. These op tions are available since Linux
kernel version 4.1. kernel version 4.1.
--ignore-zero-blocks --ignore-zero-blocks
Instruct kernel to not verify blocks that are expected to contai n zeroes and always directly Instruct kernel to not verify blocks that are expected to co ntain zeroes and always directly
return zeroes instead. return zeroes instead.
WARNING: Use this option only in very specific cases. This option is available since Linux kernel WARNING: Use this option only in very specific cases. This option is available since Linux kernel
version 4.5. version 4.5.
--check-at-most-once --check-at-most-once
Instruct kernel to verify blocks only the first time they are read from the data device, rather Instruct kernel to verify blocks only the first time they are r ead from the data device, rather
than every time. than every time.
WARNING: It provides a reduced level of security because on WARNING: It provides a reduced level of security because only o
ly offline tampering of the data ffline tampering of the data
device's content will be detected, not online tampering. This opt device's content will be detected, not online tampering. This
ion is available since Linux option is available since Linux
kernel version 4.17. kernel version 4.17.
--hash=hash --hash=hash
Hash algorithm for dm-verity. For default see --help option. Hash algorithm for dm-verity. For default see --help option.
--version --version
Show the program version. Show the program version.
--fec-device=fec_device --fec-device=fec_device
Use forward error correction (FEC) to recover from corruption if hash verification fails. Use Use forward error correction (FEC) to recover from corruption if hash verification fails. Use
encoding data from the specified device. encoding data from the specified device.
The fec device argument can be block device or file image. For fo rmat, if fec device path doesn't The fec device argument can be block device or file image. For fo rmat, if fec device path doesn't
exist, it will be created as file. exist, it will be created as file.
Block sizes for data and hash devices must match. Also, if the verity data_device is encrypted Block sizes for data and hash devices must match. Also, if the ve rity data_device is encrypted
the fec_device should be too. the fec_device should be too.
FEC calculation covers data, hash area, and optional foreign metad ata stored on the same device FEC calculation covers data, hash area, and optional foreign me tadata stored on the same device
with the hash tree (additional space after hash area). Size of th is optional additional area pro- with the hash tree (additional space after hash area). Size of th is optional additional area pro-
tected by FEC is calculated from image sizes, so you must be sure that you use the same images for tected by FEC is calculated from image sizes, so you must be sure that you use the same images for
activation. activation.
If the hash device is in a separate image, metadata covers the w hole rest of the image after the If the hash device is in a separate image, metadata covers the who le rest of the image after the
hash area. hash area.
If hash and FEC device is in the image, metadata ends on the FEC a rea offset. If hash and FEC device is in the image, metadata ends on the FEC a rea offset.
--fec-offset=bytes --fec-offset=bytes
This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding
data. data.
--fec-roots=num --fec-roots=num
Number of generator roots. This equals to the number of parity bytes in the encoding data. In Number of generator roots. This equals to the number of parity byt es 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). RS(M, N) encoding, the number of roots is M-N. M is 255 and M-N is between 2 and 24 (including).
--root-hash-file=FILE
Path to file with stored root hash in hex-encoded text.
--root-hash-signature=FILE --root-hash-signature=FILE
Path to roothash signature file used to verify the root hash (in k ernel). This feature requires Path to roothash signature file used to verify the root hash (in kernel). This feature requires
Linux kernel version 5.4 or more recent. Linux kernel version 5.4 or more recent.
--deferred
Defers device removal in close command until the last user closes
it.
--cancel-deferred
Removes a previously configured deferred device removal in close c
ommand.
RETURN CODES RETURN CODES
Veritysetup returns 0 on success and a non-zero value on error. Veritysetup returns 0 on success and a non-zero value on error.
Error codes are: Error codes are:
1 wrong parameters 1 wrong parameters
2 no permission 2 no permission
3 out of memory 3 out of memory
4 wrong device specified 4 wrong device specified
5 device already exists or device is busy. 5 device already exists or device is busy.
EXAMPLES EXAMPLES
veritysetup --data-blocks=256 format <data_device> <hash_device> 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 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). hash_device does not exist, it is created (as file image).
veritysetup format <data_device> <hash_device> veritysetup format --root-hash-file <path> <data_device> <hash_device>
Calculates and stores verification data on hash_device for the whole data Calculates and stores verification data on hash_device for the whole data
_device. _device, and store the root hash
as hex-encoded text in <path>.
veritysetup --data-blocks=256 --hash-offset=1052672 format <device> <devi ce> veritysetup --data-blocks=256 --hash-offset=1052672 format <device> <devi ce>
Verification data (hashes) is stored on the same device as data (starting at hash-offset). Hash-offset 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. must be greater than number of blocks in data-area.
veritysetup --data-blocks=256 --hash-offset=1052672 create test-device <d evice> <device> <root_hash> veritysetup --data-blocks=256 --hash-offset=1052672 create test-device <d evice> <device> <root_hash>
Activates the verity device named test-device. Options --data-blocks and --hash-offset are the same as in 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. the format command. The <root_hash> was calculated in format command.
veritysetup --data-blocks=256 --hash-offset=1052672 verify <data_device> <hash_device> <root_hash> veritysetup --data-blocks=256 --hash-offset=1052672 verify <data_device> <hash_device> <root_hash>
Verifies device without activation (in userspace). Verifies device without activation (in userspace).
veritysetup --data-blocks=256 --hash-offset=1052672 --root-hash-file
<path> verify <data_device>
<hash_device>
Verifies device without activation (in userspace). Root hash passed via a
file rather than inline.
veritysetup --fec-device=<fec_device> --fec-roots=10 format <data_device> <hash_device> veritysetup --fec-device=<fec_device> --fec-roots=10 format <data_device> <hash_device>
Calculates and stores verification and encoding data for data_device. Calculates and stores verification and encoding data for data_device.
REPORTING BUGS REPORTING BUGS
Report bugs, including ones in the documentation, on the cryptsetup maili Report bugs, including ones in the documentation, on the cryptsetup mai
ng list at <dm-crypt@saout.de> ling list at <dm-crypt@saout.de>
or in the 'Issues' section on LUKS website. Please attach the outpu or in the 'Issues' section on LUKS website. Please attach the output of
t of the failed command with the the failed command with the
--debug option added. --debug option added.
AUTHORS AUTHORS
The first implementation of veritysetup was written by Chrome OS authors. The first implementation of veritysetup was written by Chrome OS authors.
This version is based on verification code written by Mikulas Patocka <mp atocka@redhat.com> and rewritten This version is based on verification code written by Mikulas Patocka <mp atocka@redhat.com> and rewritten
for libcryptsetup by Milan Broz <gmazyland@gmail.com>. for libcryptsetup by Milan Broz <gmazyland@gmail.com>.
COPYRIGHT COPYRIGHT
Copyright © 2012-2021 Red Hat, Inc. Copyright © 2012-2021 Red Hat, Inc.
Copyright © 2012-2021 Milan Broz Copyright © 2012-2021 Milan Broz
This is free software; see the source for copying conditions. There i s NO warranty; not even for MER- This is free software; see the source for copying conditions. There is N O warranty; not even for MER-
CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
SEE ALSO SEE ALSO
The project website at https://gitlab.com/cryptsetup/cryptsetup The project website at https://gitlab.com/cryptsetup/cryptsetup
The verity on-disk format specification available at http s://gitlab.com/cryptsetup/crypt- The verity on-disk format specification available at http s://gitlab.com/cryptsetup/crypt-
setup/wikis/DMVerity setup/wikis/DMVerity
veritysetup January 2021 VERITYSETUP(8) veritysetup January 2021 VERITYSETUP(8)
 End of changes. 29 change blocks. 
34 lines changed or deleted 72 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)