diff options
Diffstat (limited to 'man/integritysetup.8')
| -rw-r--r-- | man/integritysetup.8 | 255 |
1 files changed, 255 insertions, 0 deletions
diff --git a/man/integritysetup.8 b/man/integritysetup.8 new file mode 100644 index 0000000..cce7760 --- /dev/null +++ b/man/integritysetup.8 @@ -0,0 +1,255 @@ +.TH INTEGRITYSETUP "8" "January 2021" "integritysetup" "Maintenance Commands" +.SH NAME +integritysetup - manage dm-integrity (block level integrity) volumes +.SH SYNOPSIS +.B integritysetup <options> <action> <action args> +.SH DESCRIPTION +.PP +Integritysetup is used to configure dm-integrity managed device-mapper mappings. + +Device-mapper integrity target provides read-write transparent integrity +checking of block devices. The dm-integrity target emulates additional data +integrity field per-sector. You can use this additional field directly +with integritysetup utility, or indirectly (for authenticated encryption) +through cryptsetup. + +Integritysetup supports these operations: +.PP +\fIformat\fR <device> +.IP +Formats <device> (calculates space and dm-integrity superblock and wipes the device). + +\fB<options>\fR can be [\-\-data\-device, \-\-batch\-mode, \-\-no\-wipe, \-\-journal\-size, +\-\-interleave\-sectors, \-\-tag\-size, \-\-integrity, \-\-integrity\-key\-size, +\-\-integrity\-key\-file, \-\-sector\-size, \-\-progress-frequency] + +.PP +\fIopen\fR <device> <name> +.br +\fIcreate\fR <name> <device> (\fBOBSOLETE syntax\fR) +.IP +Open a mapping with <name> backed by device <device>. + +\fB<options>\fR can be [\-\-data\-device, \-\-batch\-mode, \-\-journal\-watermark, +\-\-journal\-commit\-time, \-\-buffer\-sectors, \-\-integrity, \-\-integrity\-key\-size, +\-\-integrity\-key\-file, \-\-integrity\-no\-journal, \-\-integrity\-recalculate, +\-\-integrity\-recovery\-mode, \-\-allow\-discards] + +.PP +\fIclose\fR <name> +.IP +Removes existing mapping <name>. + +For backward compatibility, there is \fBremove\fR command alias +for the \fBclose\fR command. +.PP +\fIstatus\fR <name> +.IP +Reports status for the active integrity mapping <name>. +.PP +\fIdump\fR <device> +.IP +Reports parameters from on-disk stored 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 "\-\-version" +Show the program version. +.TP +.B "\-\-batch\-mode" +Do not ask for confirmation. +.TP +.B "\-\-progress-frequency <seconds>" +Print separate line every <seconds> with wipe progress. +.TP +.B "\-\-no\-wipe" +Do not wipe the device after format. A device that is not initially wiped will contain invalid checksums. +.TP +.B "\-\-journal\-size, \-j BYTES" +Size of the journal. +.TP +.B "\-\-interleave\-sectors SECTORS" +The number of interleaved sectors. +.TP +.B "\-\-integrity\-recalculate" +Automatically recalculate integrity tags in kernel on activation. +The device can be used during automatic integrity recalculation but becomes fully +integrity protected only after the background operation is finished. +This option is available since the Linux kernel version 4.19. +.TP +.B "\-\-journal\-watermark PERCENT" +Journal watermark in percents. When the size of the journal exceeds this watermark, +the journal flush will be started. +.TP +.B "\-\-journal\-commit\-time MS" +Commit time in milliseconds. When this time passes (and no explicit flush operation was issued), +the journal is written. +.TP +.B "\-\-tag\-size, \-t BYTES" +Size of the integrity tag per-sector (here the integrity function will store authentication tag). + +\fBNOTE:\fR The size can be smaller that output size of the hash function, in that case only +part of the hash will be stored. +.TP +.B "\-\-data\-device" +Specify a separate data device that contains existing data. The <device> then will contain +calculated integrity tags and journal for this data device. +.TP +.B "\-\-sector\-size, \-s BYTES" +Sector size (power of two: 512, 1024, 2048, 4096). +.TP +.B "\-\-buffer\-sectors SECTORS" +The number of sectors in one buffer. + +The tag area is accessed using buffers, the large buffer size means that the I/O size will +be larger, but there could be less I/Os issued. +.TP +.B "\-\-integrity, \-I ALGORITHM" +Use internal integrity calculation (standalone mode). +The integrity algorithm can be CRC (crc32c/crc32) or hash function (sha1, sha256). + +For HMAC (hmac-sha256) you have also to specify an integrity key and its size. +.TP +.B "\-\-integrity\-key\-size BYTES" +The size of the data integrity key. Maximum is 4096 bytes. +.TP +.B "\-\-integrity\-key\-file FILE" +The file with the integrity key. +.TP +.B "\-\-integrity\-no\-journal, \-D" +Disable journal for integrity device. +.TP +.B "\-\-integrity\-bitmap\-mode. \-B" +Use alternate bitmap mode (available since Linux kernel 5.2) where dm-integrity uses bitmap +instead of a journal. If a bit in the bitmap is 1, the corresponding region's data and integrity tags +are not synchronized - if the machine crashes, the unsynchronized regions will be recalculated. +The bitmap mode is faster than the journal mode, because we don't have to write the data +twice, but it is also less reliable, because if data corruption happens +when the machine crashes, it may not be detected. +.TP +.B "\-\-bitmap\-sectors\-per\-bit SECTORS" +Number of 512-byte sectors per bitmap bit, the value must be power of two. +.TP +.B "\-\-bitmap\-flush\-time MS" +Bitmap flush time in milliseconds. +.TP + +\fBWARNING:\fR +In case of a crash, it is possible that the data and integrity tag doesn't match +if the journal is disabled. +.TP +.B "\-\-integrity\-recovery\-mode. \-R" +Recovery mode (no journal, no tag checking). +.TP + +\fBNOTE:\fR The following options are intended for testing purposes only. +Using journal encryption does not make sense without encryption the data, +these options are internally used in authenticated disk encryption with \fBcryptsetup(8)\fR. +.TP +.B "\-\-journal\-integrity ALGORITHM" +Integrity algorithm for journal area. +See \-\-integrity option for detailed specification. +.TP +.B "\-\-journal\-integrity\-key\-size BYTES" +The size of the journal integrity key. Maximum is 4096 bytes. +.TP +.B "\-\-journal\-integrity\-key\-file FILE" +The file with the integrity key. +.TP +.B "\-\-journal\-crypt ALGORITHM" +Encryption algorithm for journal data area. +You can use a block cipher here such as cbc-aes or +a stream cipher, for example, chacha20 or ctr-aes. +.TP +.B "\-\-journal\-crypt\-key\-size BYTES" +The size of the journal encryption key. Maximum is 4096 bytes. +.TP +.B "\-\-journal\-crypt\-key\-file FILE" +The file with the journal encryption key. +.TP +.B "\-\-allow\-discards\fR" +Allow the use of discard (TRIM) requests for the device. +This option is available since the Linux kernel version 5.7. +.TP +The dm-integrity target is available since Linux kernel version 4.12. +.TP +\fBNOTE:\fR +Format and activation of an integrity device always require superuser +privilege because the superblock is calculated and handled in dm-integrity kernel target. + +.SH LEGACY COMPATIBILITY OPTIONS +.TP +\fBWARNING:\fR +Do not use these options until you need compatibility with specific old kernel. +.TP +.B "\-\-integrity\-legacy\-padding" +Use inefficient legacy padding. +.TP +.B "\-\-integrity\-legacy\-hmac" +Use old flawed HMAC calclation (also does not protect superblock). +.TP +.B "\-\-integrity\-legacy\-recalculate" +Allow insecure recalculating of volumes with HMAC keys (recalcualtion offset in superblock +is not protected). + +.SH RETURN CODES +Integritysetup 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 +Format the device with default standalone mode (CRC32C): + +.B "integritysetup format <device>" + +Open the device with default parameters: + +.B "integritysetup open <device> test" + +Format the device in standalone mode for use with HMAC(SHA256): + +.B "integritysetup format <device> \-\-tag\-size 32 \-\-integrity hmac\-sha256 \ +\-\-integrity\-key\-file <keyfile> \-\-integrity\-key\-size <key_bytes>" + +Open (activate) the device with HMAC(SHA256) and HMAC key in file: + +.B "integritysetup open <device> test \-\-integrity hmac\-sha256 \ +\-\-integrity\-key\-file <keyfile> \-\-integrity\-key\-size <key_bytes>" + +Dump dm-integrity superblock information: + +.B "integritysetup dump <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 integritysetup tool is written by Milan Broz <gmazyland@gmail.com> +and is part of the cryptsetup project. +.SH COPYRIGHT +Copyright \(co 2016-2021 Red Hat, Inc. +.br +Copyright \(co 2016-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 integrity on-disk format specification available at +\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity\fR |