Adding upstream version 2:2.1.0.upstream/2%2.1.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1535 insertions, 0 deletions

diff --git a/man/cryptsetup.8 b/man/cryptsetup.8
new file mode 100644
index 0000000..3c5b93a
--- /dev/null
+++ b/man/cryptsetup.8
@@ -0,0 +1,1535 @@
+.TH CRYPTSETUP "8" "January 2019" "cryptsetup" "Maintenance Commands"
+.SH NAME
+cryptsetup - manage plain dm-crypt and LUKS encrypted volumes
+.SH SYNOPSIS
+.B cryptsetup <options> <action> <action args>
+.SH DESCRIPTION
+.PP
+cryptsetup is used to conveniently setup dm-crypt managed
+device-mapper mappings. These include plain dm-crypt volumes and
+LUKS volumes. The difference is that LUKS uses a metadata header
+and can hence offer more features than plain dm-crypt. On the other
+hand, the header is visible and vulnerable to damage.
+
+In addition, cryptsetup provides limited support for the use of
+loop-AES volumes and for TrueCrypt compatible volumes.
+
+.SH PLAIN DM-CRYPT OR LUKS?
+.PP
+Unless you understand the cryptographic background well, use LUKS.
+With plain dm-crypt there are a number of possible user errors
+that massively decrease security. While LUKS cannot fix them
+all, it can lessen the impact for many of them.
+.SH WARNINGS
+.PP
+A lot of good information on the risks of using encrypted storage,
+on handling problems and on security aspects can be found in the
+\fICryptsetup FAQ\fR. Read it. Nonetheless, some risks deserve
+to be mentioned here.
+
+\fBBackup:\fR Storage media die. Encryption has no influence on that.
+Backup is mandatory for encrypted data as well, if the data has any
+worth. See the Cryptsetup FAQ for advice on how to do a backup of an
+encrypted volume.
+
+\fBCharacter encoding:\fR If you enter a
+passphrase with special symbols, the passphrase can change
+depending on character encoding. Keyboard settings can also change,
+which can make blind input hard or impossible. For
+example, switching from some ASCII 8-bit variant to UTF-8
+can lead to a different binary encoding and hence different
+passphrase seen by cryptsetup, even if what you see on
+the terminal is exactly the same. It is therefore highly
+recommended to select passphrase characters only from 7-bit
+ASCII, as the encoding for 7-bit ASCII stays the same for
+all ASCII variants and UTF-8.
+
+\fBLUKS header:\fR If the header of a LUKS volume gets damaged,
+all data is permanently lost unless you have a header-backup.
+If a key-slot is damaged, it can only be restored from a header-backup
+or if another active key-slot with known passphrase is undamaged.
+Damaging the LUKS header is something people manage to do with
+surprising frequency. This risk is the result of a trade-off
+between security and safety, as LUKS is designed for fast and
+secure wiping by just overwriting header and key-slot area.
+
+\fBPreviously used partitions:\fR If a partition was previously used,
+it is a very good idea to wipe filesystem signatures, data, etc. before
+creating a LUKS or plain dm-crypt container on it.
+For a quick removal of filesystem signatures, use "wipefs". Take care
+though that this may not remove everything. In particular, MD RAID
+signatures at the end of a device may survive. It also does not
+remove data. For a full wipe, overwrite the whole partition before
+container creation. If you do not know how to do that, the
+cryptsetup FAQ describes several options.
+
+.SH BASIC COMMANDS
+The following are valid actions for all supported device types.
+
+\fIopen\fR <device> <name> \-\-type <device_type>
+.IP
+Opens (creates a mapping with) <name> backed by device <device>.
+
+Device type can be \fIplain\fR, \fIluks\fR (default), \fIluks1\fR, \fIluks2\fR,
+\fIloopaes\fR or \fItcrypt\fR.
+
+For backward compatibility there are \fBopen\fR command aliases:
+
+\fBcreate\fR (argument-order <name> <device>): open \-\-type plain
+.br
+\fBplainOpen\fR: open \-\-type plain
+.br
+\fBluksOpen\fR: open \-\-type luks
+.br
+\fBloopaesOpen\fR: open \-\-type loopaes
+.br
+\fBtcryptOpen\fR: open \-\-type tcrypt
+
+\fB<options>\fR are type specific and are described below
+for individual device types. For \fBcreate\fR, the order of the <name>
+and <device> options is inverted for historical reasons, all other
+aliases use the standard \fB<device> <name>\fR order.
+.PP
+\fIclose\fR <name>
+.IP
+Removes the existing mapping <name> and wipes the key from kernel memory.
+
+For backward compatibility there are \fBclose\fR command aliases:
+\fBremove\fR, \fBplainClose\fR, \fBluksClose\fR, \fBloopaesClose\fR,
+\fBtcryptClose\fR (all behaves exactly the same, device type is
+determined automatically from active device).
+
+\fB<options>\fR can be [\-\-deferred]
+
+.PP
+\fIstatus\fR <name>
+.IP
+Reports the status for the mapping <name>.
+.PP
+\fIresize\fR <name>
+.IP
+Resizes an active mapping <name>.
+
+If \-\-size (in 512-bytes sectors) is not specified, the size is computed
+from the underlying device. For LUKS it is the size of the
+underlying device without the area reserved for LUKS header
+(see data payload offset in \fBluksDump\fR command).
+For plain crypt device, the whole device size is used.
+
+Note that this does not change the raw device geometry, it just
+changes how many sectors of the raw device are represented
+in the mapped device.
+
+If cryptsetup detected volume key for active device loaded in kernel keyring
+service, resize action would first try to retrieve
+the key using a token and only if it failed it'd ask for a passphrase
+to unlock a keyslot (LUKS) or to derive a volume key again (plain mode).
+The kernel keyring is used by default for LUKS2 devices.
+
+With LUKS2 device additional \fB<options>\fR can be [\-\-token\-id, \-\-token\-only,
+\-\-key\-slot, \-\-key\-file, \-\-keyfile\-size, \-\-keyfile\-offset, \-\-timeout,
+\-\-disable\-locks, \-\-disable\-keyring].
+
+.PP
+\fIrefresh\fR <name>
+.IP
+Refreshes parameters of active mapping <name>.
+
+Updates parameters of active device <name> without need to deactivate the device
+(and umount filesystem). Currently it supports parameters refresh on following
+devices: LUKS1, LUKS2 (including authenticated encryption), plain crypt
+and loopaes.
+
+Mandatory parametrs are identical to those of an open action for respective
+device type.
+
+You may change following parameters on all devices \-\-perf\-same_cpu_crypt,
+\-\-perf\-submit_from_crypt_cpus and \-\-allow\-discards.
+
+Refreshing device without any optional parameter will refresh the device
+with default setting (respective to device type).
+
+\fBLUKS2 only:\fR
+
+\-\-integrity\-no\-journal parameter affects only LUKS2 devices with
+underlying dm-integrity device.
+
+Adding option \-\-persistent stores any combination of device parameters
+above in LUKS2 metadata (only after successful refresh operation).
+
+\-\-disable\-keyring parameter refreshes a device with volume key passed
+in dm-crypt driver.
+
+.SH PLAIN MODE
+Plain dm-crypt encrypts the device sector-by-sector with a
+single, non-salted hash of the passphrase. No checks
+are performed, no metadata is used. There is no formatting operation.
+When the raw device is mapped (opened), the usual device operations
+can be used on the mapped device, including filesystem creation.
+Mapped devices usually reside in /dev/mapper/<name>.
+
+The following are valid plain device type actions:
+
+\fIopen\fR \-\-type plain <device> <name>
+.br
+\fIcreate\fR <name> <device> (\fBOBSOLETE syntax\fR)
+.IP
+Opens (creates a mapping with) <name> backed by device <device>.
+
+\fB<options>\fR can be [\-\-hash, \-\-cipher, \-\-verify-passphrase,
+\-\-sector\-size, \-\-key-file, \-\-keyfile-offset, \-\-key-size,
+\-\-offset, \-\-skip, \-\-size, \-\-readonly, \-\-shared, \-\-allow\-discards,
+\-\-refresh]
+
+Example: 'cryptsetup open \-\-type plain /dev/sda10 e1' maps the raw
+encrypted device /dev/sda10 to the mapped (decrypted) device
+/dev/mapper/e1, which can then be mounted, fsck-ed or have a
+filesystem created on it.
+.SH LUKS EXTENSION
+LUKS, the Linux Unified Key Setup, is a standard for disk encryption.
+It adds a standardized header at the start of the device,
+a key-slot area directly behind the header and the bulk
+data area behind that. The whole set is called a 'LUKS container'.
+The device that a LUKS container resides on is called a 'LUKS device'.
+For most purposes, both terms can be used interchangeably. But
+note that when the LUKS header is at a nonzero offset
+in a device, then the device is not a LUKS device anymore, but
+has a LUKS container stored in it at an offset.
+
+LUKS can manage multiple passphrases that can be individually revoked
+or changed and that can be securely scrubbed from persistent
+media due to the use of anti-forensic stripes. Passphrases
+are protected against brute-force and dictionary
+attacks by PBKDF2, which implements hash iteration and salting
+in one function.
+
+LUKS2 is a new version of header format that allows additional
+extensions like different PBKDF algorithm or authenticated encryption.
+You can format device with LUKS2 header if you specify
+\fI\-\-type luks2\fR in \fIluksFormat\fR command.
+For activation, the format is already recognized automatically.
+
+Each passphrase, also called a
+.B key
+in this document, is associated with one of 8 key-slots.
+Key operations that do not specify a slot affect the first slot
+that matches the supplied passphrase or the first empty slot if
+a new passphrase is added.
+
+The \fB<device>\fR parameter can also be specified by a LUKS UUID in the
+format UUID=<uuid>. Translation to real device name uses symlinks
+in /dev/disk/by-uuid directory.
+
+To specify a detached header, the \fB\-\-header\fR parameter can be used
+in all LUKS commands and always takes precedence over the positional
+\fB<device>\fR parameter.
+
+The following are valid LUKS actions:
+
+\fIluksFormat\fR <device> [<key file>]
+.IP
+Initializes a LUKS partition and sets the initial passphrase
+(for key-slot 0),
+either via prompting or via <key file>. Note that
+if the second argument is present, then the passphrase
+is taken from the file given there, without the need
+to use the \-\-key-file option. Also note that for both forms
+of reading the passphrase from a file you can
+give '-' as file name, which results in the passphrase being read
+from stdin and the safety-question being skipped.
+
+You can only call luksFormat on a LUKS device that is not mapped.
+
+To use LUKS2, specify \fI\-\-type luks2\fR.
+
+\fB<options>\fR can be [\-\-hash, \-\-cipher, \-\-verify\-passphrase,
+\-\-key\-size, \-\-key\-slot,
+\-\-key\-file (takes precedence over optional second argument),
+\-\-keyfile\-offset, \-\-keyfile\-size, \-\-use\-random | \-\-use\-urandom,
+\-\-uuid, \-\-master\-key\-file, \-\-iter\-time, \-\-header,
+\-\-pbkdf\-force\-iterations,
+\-\-force\-password, \-\-disable-locks].
+
+For LUKS2, additional \fB<options>\fR can be
+[\-\-integrity, \-\-integrity\-no\-wipe, \-\-sector\-size,
+\-\-label, \-\-subsystem,
+\-\-pbkdf, \-\-pbkdf\-memory, \-\-pbkdf\-parallel,
+\-\-disable\-locks, \-\-disable\-keyring,
+\-\-luks2\-metadata\-size, \-\-luks2\-keyslots\-size,
+\-\-keyslot\-cipher, \-\-keyslot\-key\-size].
+
+\fBWARNING:\fR Doing a luksFormat on an existing LUKS container will
+make all data the old container permanently irretrievable unless
+you have a header backup.
+.PP
+\fIopen\fR \-\-type luks <device> <name>
+.br
+\fIluksOpen\fR <device> <name> (\fBold syntax\fR)
+.IP
+Opens the LUKS device <device> and sets up a mapping <name> after
+successful verification of the supplied passphrase.
+
+First, the passphrase is searched in LUKS tokens. If it's not
+found in any token and also the passphrase is not supplied via \-\-key-file,
+the command prompts for it interactively.
+
+\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset,
+\-\-keyfile\-size, \-\-readonly, \-\-test\-passphrase,
+\-\-allow\-discards, \-\-header, \-\-key-slot, \-\-master\-key\-file, \-\-token\-id,
+\-\-token\-only, \-\-disable\-keyring, \-\-disable\-locks, \-\-type, \-\-refresh].
+.PP
+\fIluksSuspend\fR <name>
+.IP
+Suspends an active device (all IO operations will block
+and accesses to the device will wait indefinitely)
+and wipes the encryption
+key from kernel memory. Needs kernel 2.6.19 or later.
+
+After this operation you have to use \fIluksResume\fR to reinstate
+the encryption key and unblock the device or \fIclose\fR to remove
+the mapped device.
+
+\fBWARNING:\fR never suspend the device on which the cryptsetup binary resides.
+
+\fB<options>\fR can be [\-\-header, \-\-disable\-locks].
+.PP
+\fIluksResume\fR <name>
+.IP
+Resumes a suspended device and reinstates the encryption key.
+Prompts interactively for a passphrase if \-\-key-file is not given.
+
+\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-size, \-\-header,
+\-\-disable\-keyring, \-\-disable\-locks, \-\-type]
+.PP
+\fIluksAddKey\fR <device> [<key file with new key>]
+.IP
+Adds a new passphrase. An existing passphrase must be supplied
+interactively or via \-\-key-file.
+The new passphrase to be added can be specified interactively
+or read from the file given as positional argument.
+
+\fBNOTE:\fR with \-\-unbound option the action creates new unbound
+LUKS2 keyslot. The keyslot cannot be used for device activation.
+If you don't pass new key via \-\-master\-key\-file option,
+new random key is generated. Existing passphrase for any active keyslot
+is not required.
+
+\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset,
+\-\-keyfile\-size, \-\-new\-keyfile\-offset,
+\-\-new\-keyfile\-size, \-\-key\-slot, \-\-master\-key\-file,
+\-\-iter\-time, \-\-force\-password, \-\-header, \-\-disable\-locks,
+\-\-unbound, \-\-type, \-\-keyslot\-cipher, \-\-keyslot\-key\-size].
+.PP
+\fIluksRemoveKey\fR <device> [<key file with passphrase to be removed>]
+.IP
+Removes the supplied passphrase from the LUKS device. The
+passphrase to be removed can be specified interactively,
+as the positional argument or via \-\-key-file.
+
+\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset,
+\-\-keyfile\-size, \-\-header, \-\-disable\-locks, \-\-type]
+
+\fBWARNING:\fR If you read the passphrase from stdin
+(without further argument or with '-' as an argument
+to \-\-key\-file), batch-mode (\-q) will be implicitly
+switched on and no warning will be given when you remove the
+last remaining passphrase from a LUKS container. Removing
+the last passphrase makes the LUKS container permanently
+inaccessible.
+.PP
+\fIluksChangeKey\fR <device> [<new key file>]
+.IP
+Changes an existing passphrase. The passphrase
+to be changed must be supplied interactively or via \-\-key\-file.
+The new passphrase can be supplied interactively or in
+a file given as positional argument.
+
+If a key-slot is specified (via \-\-key-slot), the passphrase
+for that key-slot must be given and the new passphrase
+will overwrite the specified key-slot. If no key-slot
+is specified and there is still a free key-slot, then
+the new passphrase will be put into a free key-slot before the
+key-slot containing the old passphrase is purged. If there is
+no free key-slot, then the key-slot with the old passphrase is
+overwritten directly.
+
+\fBWARNING:\fR If a key-slot is overwritten, a media failure
+during this operation can cause the overwrite to fail after
+the old passphrase has been wiped and make the LUKS container
+inaccessible.
+
+\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset,
+\-\-keyfile\-size, \-\-new\-keyfile\-offset,
+\-\-new\-keyfile\-size, \-\-key\-slot, \-\-force\-password, \-\-header,
+\-\-disable\-locks, \-\-type, \-\-keyslot\-cipher, \-\-keyslot\-key\-size].
+.PP
+.PP
+\fIluksConvertKey\fR <device>
+.IP
+Converts an existing LUKS2 keyslot to new pbkdf parameters. The
+passphrase for keyslot to be converted must be supplied interactively
+or via \-\-key\-file. If no \-\-pbkdf parameters are specified LUKS2
+default pbkdf values will apply.
+
+If a keyslot is specified (via \-\-key\-slot), the passphrase for that
+keyslot must be given. If no keyslot is specified and there is still
+a free keyslot, then the new parameters will be put into a free
+keyslot before the keyslot containing the old parameters is
+purged. If there is no free keyslot, then the keyslot with the old
+parameters is overwritten directly.
+
+\fBWARNING:\fR If a keyslot is overwritten, a media failure during
+this operation can cause the overwrite to fail after the old
+parameters have been wiped and make the LUKS container inaccessible.
+
+\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset,
+\-\-keyfile\-size, \-\-key\-slot, \-\-header, \-\-disable\-locks,
+\-\-iter-time, \-\-pbkdf, \-\-pbkdf\-force\-iterations,
+\-\-pbkdf\-memory, \-\-pbkdf\-parallel,
+\-\-keyslot\-cipher, \-\-keyslot\-key\-size].
+.PP
+\fIluksKillSlot\fR <device> <key slot number>
+.IP
+Wipe the key-slot number <key slot> from the LUKS device. Except running
+in batch-mode (\-q) a remaining passphrase must be supplied,
+either interactively or via \-\-key-file.
+This command can remove the last remaining key-slot, but requires
+an interactive confirmation when doing so. Removing the last
+passphrase makes a LUKS container permanently inaccessible.
+
+\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset,
+\-\-keyfile\-size, \-\-header, \-\-disable\-locks, \-\-type].
+
+\fBWARNING:\fR If you read the passphrase from stdin
+(without further argument or with '-' as an argument
+to \-\-key-file), batch-mode (\-q) will be implicitly
+switched on and no warning will be given when you remove the
+last remaining passphrase from a LUKS container. Removing
+the last passphrase makes the LUKS container permanently
+inaccessible.
+
+\fBNOTE:\fR If there is no passphrase provided (on stdin or through
+\-\-key-file argument) and batch-mode (\-q) is active, the
+key-slot is removed without any other warning.
+
+.PP
+\fIerase\fR <device>
+.br
+\fIluksErase\fR <device>
+.IP
+Erase all keyslots and make the LUKS container permanently inaccessible.
+You do not need to provide any password for this operation.
+
+\fBWARNING:\fR This operation is irreversible.
+.PP
+\fIluksUUID\fR <device>
+.IP
+Print the UUID of a LUKS device.
+.br
+Set new UUID if \fI\-\-uuid\fR option is specified.
+.PP
+\fIisLuks\fR <device>
+.IP
+Returns true, if <device> is a LUKS device, false otherwise.
+Use option \-v to get human-readable feedback. 'Command successful.'
+means the device is a LUKS device.
+
+By specifying \-\-type you may query for specific LUKS version.
+.PP
+\fIluksDump\fR <device>
+.IP
+Dump the header information of a LUKS device.
+
+If the \-\-dump\-master\-key option is used, the LUKS device master key is
+dumped instead of the keyslot info. Together with \-\-master\-key\-file option,
+master key is dumped to a file instead of standard output. Beware that the
+master key cannot be changed without reencryption and can be used to decrypt
+the data stored in the LUKS container without a passphrase and even without the
+LUKS header. This means that if the master key is compromised, the whole device
+has to be erased to prevent further access. Use this option carefully.
+
+To dump the master key, a passphrase has to be supplied,
+either interactively or via \-\-key\-file.
+
+\fB<options>\fR can be [\-\-dump\-master\-key, \-\-key\-file,
+\-\-keyfile\-offset, \-\-keyfile\-size, \-\-header, \-\-disable\-locks,
+\-\-master\-key\-file, \-\-type].
+
+\fBWARNING:\fR If \-\-dump\-master\-key is used with \-\-key\-file
+and the argument to \-\-key\-file is '-', no validation question
+will be asked and no warning given.
+.PP
+\fIluksHeaderBackup\fR <device> \-\-header\-backup\-file <file>
+.IP
+Stores a binary backup of the LUKS header and keyslot area.
+.br
+Note: Using '-' as filename writes the header backup to a file named '-'.
+
+\fBWARNING:\fR This backup file and a passphrase valid
+at the time of backup allows decryption of the
+LUKS data area, even if the passphrase was later changed or
+removed from the LUKS device. Also note that with a header
+backup you lose the ability to securely wipe the LUKS
+device by just overwriting the header and key-slots. You
+either need to securely erase all header backups in
+addition or overwrite the encrypted data area as well.
+The second option is less secure, as some sectors
+can survive, e.g. due to defect management.
+.PP
+\fIluksHeaderRestore\fR <device> \-\-header\-backup\-file <file>
+.IP
+Restores a binary backup of the LUKS header and keyslot area
+from the specified file.
+.br
+Note: Using '-' as filename reads the header backup from a file named '-'.
+
+\fBWARNING:\fR Header and keyslots will be replaced, only
+the passphrases from the backup will work afterward.
+
+This command requires that the master key size and data offset
+of the LUKS header already on the device and of the header backup
+match. Alternatively, if there is no LUKS header on the device,
+the backup will also be written to it.
+.PP
+\fItoken\fR <add|remove|import|export> <device>
+.IP
+Action \fIadd\fR creates new keyring token to enable auto-activation of the device.
+For the auto-activation, the passphrase must be stored in keyring with the specified
+description. Usually, the passphrase should be stored in \fIuser\fR or
+\fIuser-session\fR keyring.
+The \fItoken\fR command is supported only for LUKS2.
+
+For adding new keyring token, option \-\-key\-description is mandatory.
+Also, new token is assigned to key slot specified with \-\-key\-slot option or to all
+active key slots in the case \-\-key\-slot option is omitted.
+
+To remove existing token, specify the token ID which should be removed with
+\-\-token\-id option.
+
+\fBWARNING:\fR The action \fItoken remove\fR removes any token type, not just \fIkeyring\fR
+type from token slot specified by \-\-token\-id option.
+
+Action \fIimport\fR can store arbitrary valid token json in LUKS2 header. It may be passed via
+standard input or via file passed in \-\-json\-file option. If you specify \-\-key\-slot then
+successfully imported token is also assigned to the key slot.
+
+Action \fIexport\fR writes requested token json to a file passed with \-\-json\-file or
+to standard output.
+
+\fB<options>\fR can be [\-\-header, \-\-token\-id, \-\-key\-slot, \-\-key\-description,
+\-\-disable\-locks, \-\-disable\-keyring, \-\-json\-file].
+.PP
+\fIconvert\fR <device> \-\-type <format>
+.IP
+Converts the device between LUKS1 and LUKS2 format (if possible).
+The conversion will not be performed if there is an additional LUKS2 feature or LUKS1 has
+unsupported header size.
+
+Conversion (both directions) must be performed on inactive device. There must not be active
+dm-crypt mapping established for LUKS header requested for conversion.
+
+\fB\-\-type\fR option is mandatory with following accepted values: \fIluks1\fR or \fIluks2\fR.
+
+\fBWARNING:\fR The \fIconvert\fR action can destroy the LUKS header in the case of a crash
+during conversion or if a media error occurs.
+Always create a header backup before performing this operation!
+
+\fB<options>\fR can be [\-\-header, \-\-type].
+.PP
+\fIconfig\fR <device>
+.IP
+Set permanent configuration options (store to LUKS header).
+The \fIconfig\fR command is supported only for LUKS2.
+
+The permanent options can be \fI\-\-priority\fR to set priority (normal, prefer, ignore)
+for keyslot (specified by \fI\-\-key\-slot\fR) or \fI\-\-label\fR and \fI\-\-subsystem\fR.
+
+\fB<options>\fR can be [\-\-priority, \-\-label, \-\-subsystem, \-\-key\-slot, \-\-header].
+
+.SH loop-AES EXTENSION
+cryptsetup supports mapping loop-AES encrypted partition using
+a compatibility mode.
+.PP
+\fIopen\fR \-\-type loopaes <device> <name> \-\-key\-file <keyfile>
+.br
+\fIloopaesOpen\fR <device> <name> \-\-key\-file <keyfile>  (\fBold syntax\fR)
+.IP
+Opens the loop-AES <device> and sets up a mapping <name>.
+
+If the key file is encrypted with GnuPG, then you have to use
+\-\-key\-file=\- and decrypt it before use, e.g. like this:
+.br
+gpg \-\-decrypt <keyfile> | cryptsetup loopaesOpen \-\-key\-file=\-
+<device> <name>
+
+\fBWARNING:\fR The loop-AES extension cannot use the direct input of key file
+on real terminal because the keys are separated by end-of-line and only part
+of the multi-key file would be read.
+.br
+If you need it in script, just use the pipe redirection:
+.br
+echo $keyfile | cryptsetup loopaesOpen \-\-key\-file=\- <device> <name>
+
+Use \fB\-\-keyfile\-size\fR to specify the proper key length if needed.
+
+Use \fB\-\-offset\fR to specify device offset. Note that the units
+need to be specified in number of 512 byte sectors.
+
+Use \fB\-\-skip\fR to specify the IV offset. If the original device
+used an offset and but did not use it in IV sector calculations,
+you have to explicitly use \fB\-\-skip 0\fR in addition to the offset
+parameter.
+
+Use \fB\-\-hash\fR to override the default hash function for
+passphrase hashing (otherwise it is detected according to key
+size).
+
+\fB<options>\fR can be [\-\-key\-file, \-\-key\-size, \-\-offset, \-\-skip,
+\-\-hash, \-\-readonly, \-\-allow\-discards, \-\-refresh].
+.PP
+See also section 7 of the FAQ and \fBhttp://loop-aes.sourceforge.net\fR
+for more information regarding loop-AES.
+.SH TCRYPT (TrueCrypt-compatible and VeraCrypt) EXTENSION
+cryptsetup supports mapping of TrueCrypt, tcplay or VeraCrypt
+(with \fB\-\-veracrypt\fR option) encrypted partition
+using a native Linux kernel API.
+Header formatting and TCRYPT header change is not supported, cryptsetup
+never changes TCRYPT header on-device.
+
+TCRYPT extension requires kernel userspace
+crypto API to be available (introduced in Linux kernel 2.6.38).
+If you are configuring kernel yourself, enable
+"User-space interface for symmetric key cipher algorithms" in
+"Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option).
+
+Because TCRYPT header is encrypted, you have to always provide valid
+passphrase and keyfiles.
+
+Cryptsetup should recognize all header variants, except legacy cipher chains
+using LRW encryption mode with 64 bits encryption block (namely Blowfish
+in LRW mode is not recognized, this is limitation of kernel crypto API).
+
+To recognize a VeraCrypt device use the \fB\-\-veracrypt\fR option.
+VeraCrypt is just extension of TrueCrypt header with increased
+iteration count so unlocking can take quite a lot of time (in comparison
+with TCRYPT device).
+
+To open a VeraCrypt device with a custom Personal Iteration Multiplier (PIM)
+value, \fBadditionally to \-\-veracrypt \fR use either the
+\fB\-\-veracrypt\-pim=<PIM>\fR option to directly specify the PIM on the command-
+line or use \fB\-\-veracrypt\-query\-pim\fR to be prompted for the PIM.
+
+The PIM value affects the number of iterations applied during key derivation. Please refer to
+\fBhttps://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html\fR
+for more detailed information.
+
+\fBNOTE:\fR Activation with \fBtcryptOpen\fR is supported only for cipher chains
+using LRW or XTS encryption modes.
+
+The \fBtcryptDump\fR command should work for all recognized TCRYPT devices
+and doesn't require superuser privilege.
+
+To map system device (device with boot loader where the whole encrypted
+system resides) use \fB\-\-tcrypt\-system\fR option.
+You can use partition device as the parameter (parameter must be real partition
+device, not an image in a file), then only this partition is mapped.
+
+If you have the whole TCRYPT device as a file image and you want to map multiple
+partition encrypted with system encryption, please create loopback mapping
+with partitions first (\fBlosetup \-P\fR, see \fPlosetup(8)\fR man page for more info),
+and use loop partition as the device parameter.
+
+If you use the whole base device as a parameter, one device for the whole system
+encryption is mapped. This mode is available only for backward compatibility
+with older cryptsetup versions which mapped TCRYPT system encryption
+using the whole device.
+
+To use hidden header (and map hidden device, if available),
+use \fB\-\-tcrypt\-hidden\fR option.
+
+To explicitly use backup (secondary) header, use \fB\-\-tcrypt\-backup\fR
+option.
+
+\fBNOTE:\fR There is no protection for a hidden volume if
+the outer volume is mounted. The reason is that if there
+were any protection, it would require some metadata describing
+what to protect in the outer volume and the hidden volume would
+become detectable.
+
+.PP
+\fIopen\fR \-\-type tcrypt <device> <name>
+.br
+\fItcryptOpen\fR <device> <name>  (\fBold syntax\fR)
+.IP
+Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up
+a mapping <name>.
+
+\fB<options>\fR can be [\-\-key\-file, \-\-tcrypt\-hidden,
+\-\-tcrypt\-system, \-\-tcrypt\-backup, \-\-readonly, \-\-test\-passphrase,
+\-\-allow-discards, \-\-veracrypt, \-\-veracrypt\-pim, \-\-veracrypt\-query\-pim].
+
+The keyfile parameter allows a combination of file content with the
+passphrase and can be repeated. Note that using keyfiles is compatible
+with TCRYPT and is different from LUKS keyfile logic.
+
+\fBWARNING:\fR Option \fB\-\-allow\-discards\fR cannot be combined with
+option \fB\-\-tcrypt\-hidden\fR. For normal mapping, it can cause
+the \fBdestruction of hidden volume\fR (hidden volume appears as unused space
+for outer volume so this space can be discarded).
+
+.PP
+\fItcryptDump\fR <device>
+.IP
+Dump the header information of a TCRYPT device.
+
+If the \-\-dump\-master\-key option is used, the TCRYPT device master key
+is dumped instead of TCRYPT header info. Beware that the master key
+(or concatenated master keys if cipher chain is used)
+can be used to decrypt the data stored in the TCRYPT container without
+a passphrase.
+This means that if the master key is compromised, the whole device has
+to be erased to prevent further access. Use this option carefully.
+
+\fB<options>\fR can be [\-\-dump\-master\-key, \-\-key\-file,
+\-\-tcrypt\-hidden, \-\-tcrypt\-system, \-\-tcrypt\-backup].
+
+The keyfile parameter allows a combination of file content with the
+passphrase and can be repeated.
+.PP
+See also \fBhttps://en.wikipedia.org/wiki/TrueCrypt\fR for more information regarding
+TrueCrypt.
+
+Please note that cryptsetup does not use TrueCrypt code, please report
+all problems related to this compatibility extension to the cryptsetup project.
+.SH MISCELLANEOUS
+.PP
+\fIrepair\fR <device>
+.IP
+Tries to repair the device metadata if possible. Currently supported only
+for LUKS device type.
+
+This command is useful to fix some known benign LUKS metadata
+header corruptions. Only basic corruptions of unused keyslot
+are fixable. This command will only change the LUKS header, not
+any key-slot data. You may enforce LUKS version by adding \-\-type
+option.
+
+\fBWARNING:\fR Always create a binary backup of the original
+header before calling this command.
+.PP
+\fIbenchmark\fR <options>
+.IP
+Benchmarks ciphers and KDF (key derivation function).
+Without parameters, it tries to measure few common configurations.
+
+To benchmark other ciphers or modes, you need to specify \fB\-\-cipher\fR
+and \fB\-\-key\-size\fR options or \fB\-\-hash\fR for KDF test.
+
+\fBNOTE:\fR This benchmark is using memory only and is only informative.
+You cannot directly predict real storage encryption speed from it.
+
+For testing block ciphers, this benchmark requires kernel userspace
+crypto API to be available (introduced in Linux kernel 2.6.38).
+If you are configuring kernel yourself, enable
+"User-space interface for symmetric key cipher algorithms" in
+"Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option).
+
+\fB<options>\fR can be [\-\-cipher, \-\-key\-size, \-\-hash].
+.SH OPTIONS
+.TP
+.B "\-\-verbose, \-v"
+Print more information on command execution.
+.TP
+.B "\-\-debug or \-\-debug\-json"
+Run in debug mode with full diagnostic logs. Debug output
+lines are always prefixed by '#'.
+If \-\-debug\-json is used, additional LUKS2 JSON data structures are printed.
+.TP
+.B "\-\-type <device-type>
+Specifies required device type, for more info
+read \fIBASIC COMMANDS\fR section.
+.TP
+.B "\-\-hash, \-h \fI<hash\-spec>\fR"
+Specifies the passphrase hash for \fIopen\fR (for plain and
+loopaes device types).
+
+Specifies the hash used in the LUKS key setup scheme and volume key digest
+for \fIluksFormat\fR. The specified hash is used as hash-parameter
+for PBKDF2 and for the AF splitter.
+
+The specified hash name is passed to the compiled-in crypto backend.
+Different backends may support different hashes.
+For \fIluksFormat\fR, the hash
+algorithm must provide at least 160 bits of output, which
+excludes, e.g., MD5. Do not use a non-crypto hash like
+\fB"crc32"\fR as this breaks security.
+
+Values compatible with old version of cryptsetup are
+\fB"ripemd160"\fR for \fIopen \-\-type plain\fR and
+\fB"sha1"\fR for \fIluksFormat\fR.
+
+Use \fIcryptsetup \-\-help\fR to show the defaults.
+.TP
+.B "\-\-cipher, \-c \fI<cipher\-spec>\fR"
+Set the cipher specification string.
+
+\fIcryptsetup \-\-help\fR shows the compiled-in defaults.
+The current default in the distributed sources is
+"aes-cbc-essiv:sha256" for plain dm-crypt and
+"aes-xts-plain64" for LUKS.
+
+If a hash is part of the cipher specification, then it is
+used as part of the IV generation. For example, ESSIV
+needs a hash function, while "plain64" does not and
+hence none is specified.
+
+For XTS mode you can optionally set a key size of
+512 bits with the \-s option. Key size for XTS
+mode is twice that for other modes for the same
+security level.
+
+XTS mode requires kernel 2.6.24 or later and plain64 requires
+kernel 2.6.33 or later. More information can be found in the FAQ.
+.TP
+.B "\-\-verify-passphrase, \-y"
+When interactively asking for a passphrase, ask for it twice
+and complain if both inputs do not match. Advised when creating
+a regular mapping for the first time, or when running
+\fIluksFormat\fR. Ignored on input from file or stdin.
+.TP
+.B "\-\-key-file, \-d \fIname\fR"
+Read the passphrase from file.
+
+If the name given is "-", then the passphrase will be read from stdin.
+In this case, reading will not stop at newline characters.
+
+With LUKS, passphrases supplied via \-\-key\-file are always
+the existing passphrases requested by a command, except in
+the case of \fIluksFormat\fR where \-\-key\-file is equivalent
+to the positional key file argument.
+
+If you want to set a new passphrase via key file, you have to
+use a positional argument to \fIluksAddKey\fR.
+
+See section \fBNOTES ON PASSPHRASE PROCESSING\fR for more information.
+.TP
+.B "\-\-keyfile\-offset \fIvalue\fR"
+Skip \fIvalue\fR bytes at the beginning of the key file.
+Works with all commands that accept key files.
+.TP
+.B "\-\-keyfile\-size, \-l \fIvalue\fR"
+Read a maximum of \fIvalue\fR bytes from the key file.
+The default is to read the whole file up to the compiled-in
+maximum that can be queried with \-\-help. Supplying more
+data than the compiled-in maximum aborts the operation.
+
+This option is useful
+to cut trailing newlines, for example. If \-\-keyfile\-offset
+is also given, the size count starts after the offset.
+Works with all commands that accept key files.
+.TP
+.B "\-\-new\-keyfile\-offset \fIvalue\fR"
+Skip \fIvalue\fR bytes at the start when
+adding a new passphrase from key file with
+\fIluksAddKey\fR.
+.TP
+.B "\-\-new\-keyfile\-size  \fIvalue\fR"
+Read a maximum of \fIvalue\fR bytes when adding
+a new passphrase from key file with \fIluksAddKey\fR.
+The default is to read the whole file up to the compiled-in
+maximum length that can be queried with \-\-help.
+Supplying more than the compiled in maximum aborts the
+operation.
+When \-\-new\-keyfile\-offset is also given, reading starts
+after the offset.
+.TP
+.B "\-\-master\-key\-file"
+Use a master key stored in a file.
+
+For \fIluksFormat\fR this
+allows creating a LUKS header with this specific
+master key. If the master key was taken from an existing
+LUKS header and all other parameters are the same,
+then the new header decrypts the data encrypted with the
+header the master key was taken from.
+
+Action \fIluksDump\fR together with \-\-dump\-master\-key
+option: The volume (master) key is stored in a file instead of
+being printed out to standard output.
+
+\fBWARNING:\fR If you create your own master key, you
+need to make sure to do it right. Otherwise, you can end
+up with a low-entropy or otherwise partially predictable
+master key which will compromise security.
+
+For \fIluksAddKey\fR this allows adding a new passphrase
+without having to know an existing one.
+
+For \fIopen\fR this allows one to open the LUKS device
+without giving a passphrase.
+.TP
+.B "\-\-dump\-master\-key"
+For \fIluksDump\fR this option includes the master key in the displayed
+information. Use with care, as the master key can be used to
+bypass the passphrases, see also option \-\-master\-key\-file.
+.TP
+.B "\-\-json\-file"
+Read token json from a file or write token to it. See \fItoken\fR action for more
+information. \-\-json\-file=- reads json from standard input or writes it to
+standard output respectively.
+.TP
+.B "\-\-use\-random"
+.TP
+.B "\-\-use\-urandom"
+For \fIluksFormat\fR these options define which kernel random number
+generator will be used to create the master key (which is a
+long-term key).
+
+See \fBNOTES ON RANDOM NUMBER GENERATORS\fR for more
+information. Use \fIcryptsetup \-\-help\fR
+to show the compiled-in default random number generator.
+
+\fBWARNING:\fR In a low-entropy situation (e.g. in an
+embedded system), both selections are problematic.
+Using /dev/urandom can lead to weak keys.
+Using /dev/random can block a long time, potentially
+forever, if not enough entropy can be harvested by
+the kernel.
+.TP
+.B "\-\-key\-slot, \-S <0\-7>"
+For LUKS operations that add key material, this options allows you
+to specify which key slot is selected for the new key.
+This option can be used for \fIluksFormat\fR,
+and \fIluksAddKey\fR.
+.br
+In addition, for \fIopen\fR, this option selects a
+specific key-slot to compare the passphrase against.
+If the given passphrase would only match a different key-slot,
+the operation fails.
+.TP
+.B "\-\-key\-size, \-s <bits>"
+Sets key size in bits. The argument has to be a multiple of
+8. The possible key-sizes are limited by the cipher and
+mode used.
+
+See /proc/crypto for more information. Note that key-size
+in /proc/crypto is stated in bytes.
+
+This option can be used for \fIopen \-\-type plain\fR or \fIluksFormat\fR.
+All other LUKS actions will use the key-size specified in the LUKS header.
+Use \fIcryptsetup \-\-help\fR to show the compiled-in defaults.
+.TP
+.B "\-\-size, \-b <number of 512 byte sectors>"
+Set the size of the device in sectors of 512 bytes.
+This option is only relevant for the \fIopen\fR and \fIresize\fR
+actions.
+.TP
+.B "\-\-offset, \-o <number of 512 byte sectors>"
+Start offset in the backend device in 512-byte sectors.
+This option is only relevant for the \fIopen\fR action with plain
+or loopaes device types or for LUKS devices in \fIluksFormat\fR.
+
+For LUKS, the \-\-offset option sets the data offset (payload) of data
+device and must be be aligned to 4096-byte sectors (must be multiple of 8).
+This option cannot be combined with \-\-align\-payload option.
+.TP
+.B "\-\-skip, \-p <number of 512 byte sectors>"
+Start offset used in IV calculation in 512-byte sectors
+(how many sectors of the encrypted data to skip at the beginning).
+This option is only relevant for the \fIopen\fR action with plain
+or loopaes device types.
+
+Hence, if \-\-offset \fIn\fR, and \-\-skip \fIs\fR, sector \fIn\fR
+(the first sector of the encrypted device) will get a sector number
+of \fIs\fR for the IV calculation.
+.TP
+.B "\-\-readonly, \-r"
+set up a read-only mapping.
+.TP
+.B "\-\-shared"
+Creates an additional mapping for one common
+ciphertext device. Arbitrary mappings are supported.
+This option is only relevant for the
+\fIopen \-\-type plain\fR action. Use \-\-offset, \-\-size and \-\-skip to
+specify the mapped area.
+.TP
+.B "\-\-pbkdf <PBKDF spec>"
+Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS keyslot.
+The PBKDF can be: \fIpbkdf2\fR (for PBKDF2 according to RFC2898),
+\fIargon2i\fR for Argon2i or \fIargon2id\fR for Argon2id
+(see https://www.cryptolux.org/index.php/Argon2 for more info).
+
+For LUKS1, only PBKDF2 is accepted (no need to use this option).
+The default PBKDF2 for LUKS2 is set during compilation time
+and is available in \fIcryptsetup \-\-help\fR output.
+
+A PBKDF is used for increasing dictionary and brute-force attack cost
+for keyslot passwords. The parameters can be time, memory and parallel cost.
+
+For PBKDF2, only time cost (number of iterations) applies.
+For Argon2i/id, there is also memory cost (memory required during
+the process of key derivation) and parallel cost (number of threads
+that run in parallel during the key derivation.
+
+Note that increasing memory cost also increases time, so the final
+parameter values are measured by a benchmark. The benchmark
+tries to find iteration time (\fI\-\-iter\-time\fR) with required
+memory cost \fI\-\-pbkdf\-memory\fR. If it is not possible,
+the memory cost is decreased as well.
+The parallel cost \fI\-\-pbkdf\-parallel\fR is constant, is is checked
+against available CPU cores (if not available, it is decreased) and the maximum
+parallel cost is 4.
+
+You can see all PBKDF parameters for particular LUKS2 keyslot with
+\fIluksDump\fR command.
+
+\fBNOTE:\fR If you do not want to use benchmark and want to specify
+all parameters directly, use \fI\-\-pbkdf\-force\-iterations\fR with
+\fI\-\-pbkdf\-memory\fR and \fI\-\-pbkdf\-parallel\fR.
+This will override the values without benchmarking.
+Note it can cause extremely long unlocking time. Use only is specified
+cases, for example, if you know that the formatted device will
+be used on some small embedded system.
+In this case, the LUKS PBKDF2 digest will be set to the minimum iteration count.
+.TP
+.B "\-\-iter\-time, \-i <number of milliseconds>"
+The number of milliseconds to spend with PBKDF passphrase processing.
+This option is only relevant for LUKS operations that set or change
+passphrases, such as \fIluksFormat\fR or \fIluksAddKey\fR.
+Specifying 0 as parameter selects the compiled-in default.
+.TP
+.B "\-\-pbkdf\-memory <number>"
+Set the memory cost for PBKDF (for Argon2i/id the number represents kilobytes).
+Note that it is maximal value, PBKDF benchmark or available physical memory
+can decrease it.
+This option is not available for PBKDF2.
+.TP
+.B "\-\-pbkdf\-parallel <number>"
+Set the parallel cost for PBKDF (number of threads, up to 4).
+Note that it is maximal value, it is decreased automatically if
+CPU online count is lower.
+This option is not available for PBKDF2.
+.TP
+.B "\-\-pbkdf\-force\-iterations <num>"
+Avoid PBKDF benchmark and set time cost (iterations) directly.
+It can be used for LUKS/LUKS2 device only.
+See \fI\-\-pbkdf\fR option for more info.
+.TP
+.B "\-\-batch\-mode, \-q"
+Suppresses all confirmation questions. Use with care!
+
+If the \-y option is not specified, this option also switches off
+the passphrase verification for \fIluksFormat\fR.
+.TP
+.B "\-\-progress-frequency <seconds>"
+Print separate line every <seconds> with wipe progress.
+.TP
+.B "\-\-timeout, \-t <number of seconds>"
+The number of seconds to wait before timeout on passphrase input
+via terminal. It is relevant every time a passphrase is asked,
+for example for \fIopen\fR, \fIluksFormat\fR or \fIluksAddKey\fR.
+It has no effect if used in conjunction with \-\-key-file.
+.br
+This option is useful when the system
+should not stall if the user does not input a passphrase,
+e.g. during boot. The default is a value of 0 seconds,
+which means to wait forever.
+.TP
+.B "\-\-tries, \-T"
+How often the input of the passphrase shall be retried.
+This option is relevant
+every time a passphrase is asked, for example for
+\fIopen\fR, \fIluksFormat\fR or \fIluksAddKey\fR.
+The default is 3 tries.
+.TP
+.B "\-\-align\-payload <number of 512 byte sectors>"
+Align payload at a boundary of \fIvalue\fR 512-byte sectors.
+This option is relevant for \fIluksFormat\fR.
+
+If not specified, cryptsetup tries to use the topology info
+provided by the kernel for the underlying device to get the optimal alignment.
+If not available (or the calculated value is a multiple of the default)
+data is by default aligned to a 1MiB boundary (i.e. 2048 512-byte sectors).
+
+For a detached LUKS header, this option specifies the offset on the
+data device. See also the \-\-header option.
+
+\fBWARNING:\fR This option is DEPRECATED and has often unexpected impact
+to the data offset and keyslot area size (for LUKS2) due to the complex rounding.
+For fixed data device offset use \fI\-\-offset\fR option instead.
+
+.TP
+.B "\-\-uuid=\fIUUID\fR"
+Use the provided \fIUUID\fR for the \fIluksFormat\fR command
+instead of generating a new one. Changes the existing UUID when
+used with the \fIluksUUID\fR command.
+
+The UUID must be provided in the standard UUID format,
+e.g. 12345678-1234-1234-1234-123456789abc.
+.TP
+.B "\-\-allow\-discards\fR"
+Allow the use of discard (TRIM) requests for the device.
+This option is only relevant for \fIopen\fR action.
+
+\fBWARNING:\fR This command can have a negative security impact
+because it can make filesystem-level operations visible on
+the physical device. For example, information leaking
+filesystem type, used space, etc. may be extractable from
+the physical device if the discarded blocks can be located
+later. If in doubt, do not use it.
+
+A kernel version of 3.1 or later is needed. For earlier kernels,
+this option is ignored.
+.TP
+.B "\-\-perf\-same_cpu_crypt\fR"
+Perform encryption using the same cpu that IO was submitted on.
+The default is to use an unbound workqueue so that encryption work
+is automatically balanced between available CPUs.
+This option is only relevant for \fIopen\fR action.
+
+\fBNOTE:\fR This option is available only for low-level dm-crypt
+performance tuning, use only if you need a change to default dm-crypt
+behaviour. Needs kernel 4.0 or later.
+.TP
+.B "\-\-perf\-submit_from_crypt_cpus\fR"
+Disable offloading writes to a separate thread after encryption.
+There are some situations where offloading write bios from the
+encryption threads to a single thread degrades performance
+significantly.  The default is to offload write bios to the same
+thread.
+This option is only relevant for \fIopen\fR action.
+
+\fBNOTE:\fR This option is available only for low-level dm-crypt
+performance tuning, use only if you need a change to default dm-crypt
+behaviour. Needs kernel 4.0 or later.
+.TP
+.B "\-\-test\-passphrase\fR"
+Do not activate the device, just verify passphrase.
+This option is only relevant for \fIopen\fR action (the device
+mapping name is not mandatory if this option is used).
+.TP
+.B "\-\-header\fR <device or file storing the LUKS header>"
+Use a detached (separated) metadata device or file where the
+LUKS header is stored. This option allows one to store ciphertext
+and LUKS header on different devices.
+
+This option is only relevant for LUKS devices and can be
+used with the \fIluksFormat\fR, \fIopen\fR, \fIluksSuspend\fR,
+\fIluksResume\fR, \fIstatus\fR and \fIresize\fR commands.
+
+For \fIluksFormat\fR with a file name as the argument to \-\-header,
+the file will be automatically created if it does not exist.
+See the cryptsetup FAQ for header size calculation.
+
+For other commands that change the LUKS header (e.g. \fIluksAddKey\fR),
+specify the device or file with the LUKS header directly as the
+LUKS device.
+
+If used with \fIluksFormat\fR, the \-\-align\-payload option is taken
+as absolute sector alignment on ciphertext device and can be zero.
+
+\fBWARNING:\fR There is no check whether the ciphertext device specified
+actually belongs to the header given. In fact, you can specify an
+arbitrary device as the ciphertext device for \fIopen\fR
+with the \-\-header option. Use with care.
+.TP
+.B "\-\-header\-backup\-file <file>"
+Specify file with header backup for \fIluksHeaderBackup\fR or
+\fIluksHeaderBackup\fR actions.
+.TP
+.B "\-\-force\-password"
+Do not use password quality checking for new LUKS passwords.
+
+This option applies only to \fIluksFormat\fR, \fIluksAddKey\fR and
+\fIluksChangeKey\fR and is ignored if cryptsetup is built without
+password quality checking support.
+
+For more info about password quality check, see the manual page
+for \fBpwquality.conf(5)\fR and \fBpasswdqc.conf(5)\fR.
+.TP
+.B "\-\-deferred"
+Defers device removal in \fIclose\fR command until the last user closes it.
+.TP
+.B "\-\-disable\-locks"
+Disable lock protection for metadata on disk.
+This option is valid only for LUKS2 and ignored for other formats.
+
+\fBWARNING:\fR Do not use this option unless you run cryptsetup in
+a restricted environment where locking is impossible to perform
+(where /run directory cannot be used).
+.TP
+.B "\-\-disable\-keyring"
+Do not load volume key in kernel keyring but use store key directly
+in the dm-crypt target.
+This option is supported only for the LUKS2 format.
+.TP
+.B "\-\-key\-description <text>"
+Set key description in keyring for use with \fItoken\fR command.
+.TP
+.B "\-\-priority <normal|prefer|ignore>"
+Set a priority for LUKS2 keyslot.
+The \fIprefer\fR priority marked slots are tried before \fInormal\fR priority.
+The \fIignored\fR priority means, that slot is never used, if not explicitly
+requested by \fI\-\-key\-slot\fR option.
+.TP
+.B "\-\-token\-id"
+Specify what token to use in actions \fItoken\fR, \fIopen\fR or \fIresize\fR.
+If omitted, all available tokens will be checked before proceeding further with
+passphrase prompt.
+.TP
+.B "\-\-token\-only"
+Do not proceed further with action (any of \fItoken\fR, \fIopen\fR or
+\fIresize\fR) if token activation failed. Without the option,
+action asks for passphrase to proceed further.
+.TP
+.B "\-\-sector\-size <bytes>"
+Set sector size for use with disk encryption. It must be power of two
+and in range 512 - 4096 bytes. The default is 512 bytes sectors.
+This option is available only in the LUKS2 mode.
+
+Note that if sector size is higher than underlying device hardware sector
+and there is not integrity protection that uses data journal, using
+this option can increase risk on incomplete sector writes during a power fail.
+
+If used together with \fI\-\-integrity\fR option and dm-integrity journal,
+the atomicity of writes is guaranteed in all cases (but it cost write
+performance - data has to be written twice).
+
+Increasing sector size from 512 bytes to 4096 bytes can provide better
+performance on most of the modern storage devices and also with some
+hw encryption accelerators.
+.TP
+.B "\-\-persistent"
+If used with LUKS2 devices and activation commands like \fIopen\fR,
+the specified activation flags are persistently written into metadata
+and used next time automatically even for normal activation.
+(No need to use cryptab or other system configuration files.)
+Only \fI\-\-allow-discards\fR, \fI\-\-perf\-same_cpu_crypt\fR,
+\fI\-\-perf\-submit_from_crypt_cpus\fR and \fI\-\-integrity\-no\-journal\fR
+can be stored persistently.
+.TP
+.B "\-\-refresh"
+Refreshes an active device with new set of parameters. See action \fIrefresh\fR description
+for more details.
+.TP
+.B "\-\-label <LABEL>"
+.B "\-\-subsystem <SUBSYSTEM>"
+Set label and subsystem description for LUKS2 device, can be used
+in \fIconfig\fR and \fIformat\fR actions.
+The label and subsystem are optional fields and can be later used in udev scripts
+for triggering user actions once device marked by these labels is detected.
+.TP
+.B "\-\-integrity <integrity algorithm>"
+Specify integrity algorithm to be used for authenticated disk encryption in LUKS2.
+
+\fBWARNING: This extension is EXPERIMENTAL\fR and requires dm-integrity
+kernel target (available since kernel version 4.12).
+For native AEAD modes, also enable "User-space interface for AEAD cipher algorithms"
+in "Cryptographic API" section (CONFIG_CRYPTO_USER_API_AEAD .config option).
+
+For more info, see \fIAUTHENTICATED DISK ENCRYPTION\fR section.
+.TP
+.B "\-\-luks2\-metadata\-size <size>"
+This option can be used to enlarge the LUKS2 metadata (JSON) area.
+The size includes 4096 bytes for binary metadata (usable JSON area is smaller
+of the binary area).
+According to LUKS2 specification, only these values are valid:
+16, 32, 64, 128, 256, 512, 1024, 2048 and 4096 kB
+The <size> can be specified with unit suffix (for example 128k).
+.TP
+.B "\-\-luks2\-keyslots\-size <size>"
+This option can be used to set specific size of the LUKS2 binary keyslot area
+(key material is encrypted there). The value must be aligned to multiple
+of 4096 bytes with maximum size 128MB.
+The <size> can be specified with unit suffix (for example 128k).
+.TP
+.B "\-\-keyslot\-cipher <cipher\-spec>"
+This option can be used to set specific cipher encryption for the LUKS2 keyslot area.
+.TP
+.B "\-\-keyslot\-key\-size <bits>"
+This option can be used to set specific key size for the LUKS2 keyslot area.
+.TP
+.B "\-\-integrity\-no\-journal"
+Activate device with integrity protection without using data journal (direct
+write of data and integrity tags).
+Note that without journal power fail can cause non-atomic write and data corruption.
+Use only if journalling is performed on a different storage layer.
+.TP
+.B "\-\-integrity\-no\-wipe"
+Skip wiping of device authentication (integrity) tags. If you skip this
+step, sectors will report invalid integrity tag until an application write
+to the sector.
+
+\fBNOTE:\fR Even some writes to the device can fail if the write is not
+aligned to page size and page-cache initiates read of a sector with invalid
+integrity tag.
+.TP
+.B "\-\-unbound"
+
+Creates new LUKS2 unbound keyslot. See \fIluksAddKey\fR action for more
+details.
+.TP
+.B "\-\-tcrypt\-hidden"
+.B "\-\-tcrypt\-system"
+.B "\-\-tcrypt\-backup"
+Specify which TrueCrypt on-disk header will be used to open the device.
+See \fITCRYPT\fR section for more info.
+.TP
+.B "\-\-veracrypt"
+Allow VeraCrypt compatible mode. Only for TCRYPT extension.
+See \fITCRYPT\fR section for more info.
+.TP
+.B "\-\-veracrypt\-pim"
+.B "\-\-veracrypt\-query\-pim"
+Use a custom Personal Iteration Multiplier (PIM) for VeraCrypt device.
+See \fITCRYPT\fR section for more info.
+.TP
+.B "\-\-version"
+Show the program version.
+.TP
+.B "\-\-usage"
+Show short option help.
+.TP
+.B "\-\-help, \-?"
+Show help text and default parameters.
+.SH RETURN CODES
+Cryptsetup returns 0 on success and a non-zero value on error.
+
+Error codes are: 1 wrong parameters, 2 no permission (bad passphrase),
+3 out of memory, 4 wrong device specified, 5 device already exists
+or device is busy.
+.SH NOTES ON PASSPHRASE PROCESSING FOR PLAIN MODE
+Note that no iterated hashing or salting is done in plain mode.
+If hashing is done, it is a single direct hash. This means that
+low-entropy passphrases are easy to attack in plain mode.
+
+\fBFrom a terminal\fR: The passphrase is read until the
+first newline, i.e. '\\n'.
+The input without the newline character is processed with
+the default hash or the hash specified with \-\-hash.
+The hash result will be truncated to the key size
+of the used cipher, or the size specified with \-s.
+
+\fBFrom stdin\fR: Reading will continue until a newline (or until
+the maximum input size is reached), with the trailing newline
+stripped. The maximum input size is defined by the same
+compiled-in default as for the maximum key file size and can
+be overwritten using \-\-keyfile-size option.
+
+The data read will be hashed with the default hash
+or the hash specified with \-\-hash.
+The hash result will be truncated to the key size
+of the used cipher, or the size specified with \-s.
+
+Note that if \-\-key-file=- is used for reading the key
+from stdin, trailing newlines are not stripped from the input.
+
+If "plain" is used as argument to \-\-hash, the input
+data will not be hashed. Instead, it will be zero padded (if
+shorter than the key size) or truncated (if longer than the
+key size) and used directly as the binary key. This is useful for
+directly specifying a binary key.
+No warning will be given if the amount of data read from stdin is
+less than the key size.
+
+\fBFrom a key file\fR: It will be truncated to the
+key size of the used cipher or the size given by \-s
+and directly used as a binary key.
+
+\fBWARNING\fR: The \-\-hash argument is being ignored.
+The \-\-hash option is usable only for stdin input in plain mode.
+
+If the key file is shorter than the key, cryptsetup
+will quit with an error.
+The maximum input size is defined by the same
+compiled-in default as for the maximum key file size and can
+be overwritten using \-\-keyfile-size option.
+
+
+.SH NOTES ON PASSPHRASE PROCESSING FOR LUKS
+LUKS uses PBKDF2 to protect against dictionary attacks
+and to give some protection to low-entropy passphrases
+(see RFC 2898 and the cryptsetup FAQ).
+
+\fBFrom a terminal\fR: The passphrase is read until the
+first newline and then processed by PBKDF2 without
+the newline character.
+
+\fBFrom stdin\fR:
+LUKS will read passphrases from stdin up to the
+first newline character or the compiled-in
+maximum key file length. If \-\-keyfile\-size is
+given, it is ignored.
+
+\fBFrom key file\fR:
+The complete keyfile is read up to the compiled-in
+maximum size. Newline characters do not terminate the
+input. The \-\-keyfile\-size option can be used to limit
+what is read.
+
+\fBPassphrase processing\fR:
+Whenever a passphrase is added to a LUKS header (luksAddKey, luksFormat),
+the user may specify how much the time the passphrase processing
+should consume. The time is used to determine the iteration count
+for PBKDF2 and higher times will offer better protection for
+low-entropy passphrases, but open will take longer to
+complete. For passphrases that have entropy higher than the
+used key length, higher iteration times will not increase security.
+
+The default setting of one or two seconds is sufficient for most
+practical cases. The only exception is a low-entropy
+passphrase used on a device with a slow CPU, as this will
+result in a low iteration count. On a slow device, it may
+be advisable to increase the iteration time using the
+\-\-iter\-time option in order to obtain a higher
+iteration count. This does slow down all later luksOpen
+operations accordingly.
+.SH INCOHERENT BEHAVIOR FOR INVALID PASSPHRASES/KEYS
+LUKS checks for a valid passphrase when an encrypted partition
+is unlocked. The behavior of plain dm-crypt is different.
+It will always decrypt with the passphrase given. If the
+given passphrase is wrong, the device mapped by plain
+dm-crypt will essentially still contain encrypted data and
+will be unreadable.
+.SH NOTES ON SUPPORTED CIPHERS, MODES, HASHES AND KEY SIZES
+The available combinations of ciphers, modes, hashes and key sizes
+depend on kernel support. See /proc/crypto for a list of available
+options. You might need to load additional kernel crypto modules
+in order to get more options.
+
+For the \-\-hash option, if the crypto backend is libgcrypt,
+then all algorithms supported by the gcrypt library are available.
+For other crypto backends, some algorithms may be missing.
+.SH NOTES ON PASSPHRASES
+Mathematics can't be bribed. Make sure you keep your passphrases safe.
+There are a few nice tricks for constructing a fallback, when suddenly
+out of the blue, your brain refuses to cooperate.
+These fallbacks need LUKS, as it's only possible with LUKS
+to have multiple passphrases. Still, if your attacker model does
+not prevent it, storing your passphrase in a sealed envelope somewhere
+may be a good idea as well.
+.SH NOTES ON RANDOM NUMBER GENERATORS
+Random Number Generators (RNG) used in cryptsetup are always the
+kernel RNGs without any modifications or additions to data stream
+produced.
+
+There are two types of randomness cryptsetup/LUKS needs. One type
+(which always uses /dev/urandom) is used for salts, the AF splitter
+and for wiping deleted keyslots.
+
+The second type is used for the volume (master) key. You can switch
+between using /dev/random and /dev/urandom  here, see
+\fP\-\-use\-random\fR and \fP\-\-use\-urandom\fR
+options. Using /dev/random on a system without enough entropy sources
+can cause \fPluksFormat\fR to block until the requested amount of
+random data is gathered. In a low-entropy situation (embedded system),
+this can take a very long time and potentially forever. At the same
+time, using /dev/urandom in a low-entropy situation will
+produce low-quality keys. This is a serious problem, but solving
+it is out of scope for a mere man-page.
+See \fPurandom(4)\fR for more information.
+.SH AUTHENTICATED DISK ENCRYPTION (EXPERIMENTAL)
+Since Linux kernel version 4.12 dm-crypt supports authenticated
+disk encryption.
+
+Normal disk encryption modes are length-preserving (plaintext sector
+is of the same size as a ciphertext sector) and can provide only
+confidentiality protection, but not cryptographically sound
+data integrity protection.
+
+Authenticated modes require additional space per-sector for
+authentication tag and use Authenticated Encryption with Additional
+Data (AEAD) algorithms.
+
+If you configure LUKS2 device with data integrity protection,
+there will be an underlying dm-integrity device, which provides
+additional per-sector metadata space and also provide data
+journal protection to ensure atomicity of data and metadata update.
+Because there must be additional space for metadata and journal,
+the available space for the device will be smaller than for
+length-preserving modes.
+
+The dm-crypt device then resides on top of such a dm-integrity device.
+All activation and deactivation of this device stack is performed
+by cryptsetup, there is no difference in using \fIluksOpen\fR
+for integrity protected devices.
+If you want to format LUKS2 device with data integrity protection,
+use \fI\-\-integrity\fR option.
+
+Some integrity modes requires two independent keys (key for encryption
+and for authentication). Both these keys are stored in one LUKS keyslot.
+
+\fBWARNING:\fR All support for authenticated modes is experimental
+and there are only some modes available for now. Note that there
+are a very few authenticated encryption algorithms that are suitable
+for disk encryption.
+
+.SH NOTES ON LOOPBACK DEVICE USE
+Cryptsetup is usually used directly on a block device (disk
+partition or LVM volume). However, if the device argument is a
+file, cryptsetup tries to allocate a loopback device
+and map it into this file. This mode requires Linux kernel 2.6.25
+or more recent which supports the loop autoclear flag (loop device is
+cleared on the last close automatically). Of course, you can
+always map a file to a loop-device manually. See the
+cryptsetup FAQ for an example.
+
+When device mapping is active, you can see the loop backing file in
+the status command output. Also see losetup(8).
+.SH LUKS2 header locking
+.PP
+The LUKS2 on-disk metadata is updated in several steps and
+to achieve proper atomic update, there is a locking mechanism.
+For an image in file, code uses \fIflock(2)\fR system call.
+For a block device, lock is performed over a special file stored
+in a locking directory (by default \fI/run/lock/cryptsetup\fR).
+The locking directory should be created with the proper security
+context by the distribution during the boot-up phase.
+Only LUKS2 uses locks, other formats do not use this mechanism.
+.SH DEPRECATED ACTIONS
+.PP
+The \fIreload\fR action is no longer supported.
+Please use \fIdmsetup(8)\fR if you need to
+directly manipulate with the device mapping table.
+.PP
+The \fIluksDelKey\fR was replaced with \fIluksKillSlot\fR.
+.PP
+.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
+cryptsetup originally written by Jana Saout <jana@saout.de>
+.br
+The LUKS extensions and original man page were written by
+Clemens Fruhwirth <clemens@endorphin.org>.
+.br
+Man page extensions by Milan Broz <gmazyland@gmail.com>.
+.br
+Man page rewrite and extension by Arno Wagner <arno@wagner.name>.
+.SH COPYRIGHT
+Copyright \(co 2004 Jana Saout
+.br
+Copyright \(co 2004-2006 Clemens Fruhwirth
+.br
+Copyright \(co 2012-2014 Arno Wagner
+.br
+Copyright \(co 2009-2019 Red Hat, Inc.
+.br
+Copyright \(co 2009-2019 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 LUKS website at \fBhttps://gitlab.com/cryptsetup/cryptsetup/\fR
+
+The cryptsetup FAQ, contained in the distribution package and
+online at
+\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions\fR
+
+The cryptsetup mailing list and list archive, see FAQ entry 1.6.
+
+The LUKS on-disk format specification available at
+\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/Specification\fR