cryptsetup/man/integritysetup.8

.TH INTEGRITYSETUP "8" "May 2017" "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 [\-\-batch-mode, \-\-no-wipe, \-\-journal-size, \-\-interleave-sectors,
\-\-tag-size, \-\-integrity, \-\-integrity-key-size, \-\-integrity-key-file, \-\-sector-size]

.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 [\-\-batch-mode, \-\-journal-watermark, \-\-journal-commit-time,
\-\-buffer-sectors, \-\-integrity, \-\-integrity-key-size, \-\-integrity-key-file,
\-\-integrity-no-journal, \-\-integrity-recovery-mode]

.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 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 "\-\-no\-wipe"
Do not wipe device after format. Deviced that is not initially wiped will contain invalid checksums.
.TP
.B "\-\-journal\-size=bytes"
Size of journal.
.TP
.B "\-\-interleave\-sectors=SECTORS"
Number of interleaved sectors.
.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=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 "\-\-sector\-size=bytes"
Size of sector (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=algorithm"
Use intenal integrity calculation (standalone mode).
The integrity algorithm can be CRC (crc32c/crc32) or hash function (sha1, sha256).

For HMAC (hmac-sha256) you have to also specify a integrity key and its size.
.TP
.B "\-\-integrity\-key\-size=bits"
The size of the data integrity key.
.TP
.B "\-\-integrity\-key\-file=file"
The file with the integrity key.
.TP
.B "\-\-integrity\-no\-journal"
Disable journal for integrity device.

\fBWARNING:\fR In case of crash, it is possible that the data and integrity tag doesn't match if journal is disabled.
.TP
.B "\-\-integrity\-recovery\-mode"
Recovery mode (no journal, no tag checking).
.TP

The dm-integrity target is available since Linux kernel version 4.12.

.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 and code is written by Milan Broz <gmazyland@gmail.com>
and is part of cryptsetup project.
.SH COPYRIGHT
Copyright \(co 2016-2017 Red Hat, Inc.
.br
Copyright \(co 2016-2017 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