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, 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