-.TH CRYPTSETUP "8" "May 2012" "cryptsetup" "Maintenance Commands"
+.TH CRYPTSETUP "8" "December 2013" "cryptsetup" "Maintenance Commands"
.SH NAME
cryptsetup - manage plain dm-crypt and LUKS encrypted volumes
.SH SYNOPSIS
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
+historic loopaes volumes and for TrueCrypt compatible volumes.
+
.SH PLAIN DM-CRYPT OR LUKS?
.PP
Unless you understand the cryptographic background well, use LUKS.
\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
+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 to that, the
cryptsetup FAQ describes several options.
.SH BASIC COMMANDS
The following are valid actions for all supported device types.
-\fIopen\fR <name> <device> \-\-type <device_type>
+\fIopen\fR <device> <name> \-\-type <device_type>
.IP
-Opens (creates a mapping) with <name> backed by device <device>.
+Opens (creates a mapping with) <name> backed by device <device>.
Device type can be \fIplain\fR, \fIluks\fR (default), \fIloopaes\fR
or \fItcrypt\fR.
For backward compatibility there are \fBopen\fR command aliases:
-\fBcreate\fR: open \-\-type plain <device> <name>\fR switched arguments)
+\fBcreate\fR (argument-order <name> <device>): open \-\-type plain
.br
\fBplainOpen\fR: open \-\-type plain
.br
\fBtcryptOpen\fR: open \-\-type tcrypt
\fB<options>\fR are type specific and are described below
-for individual device types.
+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
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 (created), the usual device operations
+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>.
.br
\fIcreate\fR <name> <device> (\fBOBSOLETE syntax\fR)
.IP
-Creates a mapping with <name> backed by device <device>.
+Opens (creates a mapping with) <name> backed by device <device>.
\fB<options>\fR can be [\-\-hash, \-\-cipher, \-\-verify-passphrase,
\-\-key-file, \-\-keyfile-offset, \-\-key-size, \-\-offset, \-\-skip, \-\-size,
\-\-readonly, \-\-shared, \-\-allow-discards]
-Example: 'cryptsetup open --type plain /dev/sda10 e1' maps the raw
+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.
that matches the supplied passphrase or the first empty slot if
a new passphrase is added.
+The \fB<device>\fR parameter can be also 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 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),
+(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
You can only call luksFormat on a LUKS device that is not mapped.
-\fB<options>\fR can be [\-\-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].
+\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,
+\-\-force\-password].
\fBWARNING:\fR Doing a luksFormat on an existing LUKS container will
make all data the old container permanently irretrievable, unless
If the passphrase is not supplied via \-\-key-file, the command
prompts for it interactively.
-The <device> parameter can be also specified by LUKS UUID in the
-format UUID=<uuid>, which uses the symlinks in /dev/disk/by-uuid.
-
-\fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset,
-\-\-keyfile-size, \-\-readonly, \-\-test-passphrase,
-\-\-allow-discards, \-\-header, \-\-key-slot, \-\-master-key-file].
+\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset,
+\-\-keyfile\-size, \-\-readonly, \-\-test\-passphrase,
+\-\-allow\-discards, \-\-header, \-\-key-slot, \-\-master\-key\-file].
.PP
\fIluksSuspend\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]
+\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-size, \-\-header]
.PP
\fIluksAddKey\fR <device> [<key file with new key>]
.IP
The new passphrase to be added can be specified interactively
or read from the file given as positional argument.
-\fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset,
-\-\-keyfile-size, \-\-new-keyfile-offset,
-\-\-new-keyfile-size, \-\-key-slot, \-\-master-key-file].
+\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].
.PP
\fIluksRemoveKey\fR <device> [<key file with passphrase to be removed>]
.IP
passphrase to be removed can be specified interactively,
as positional argument or via \-\-key-file.
-\fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset,
-\-\-keyfile-size]
+\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset,
+\-\-keyfile\-size, \-\-header]
\fBWARNING:\fR If you read the passphrase from stdin
-(without further argument or with '-' as argument
-to \-\-key-file), batch-mode (-q) will be implicitely
+(without further argument or with '-' as argument
+to \-\-key\-file), batch-mode (\-q) will be implicitely
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
\fIluksChangeKey\fR <device> [<new key file>]
.IP
Changes an existing passphrase. The passphrase
-to be changed must be supplied interactively or via \-\-key-file.
+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.
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].
+\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset,
+\-\-keyfile\-size, \-\-new\-keyfile\-offset,
+\-\-new\-keyfile\-size, \-\-key\-slot, \-\-force\-password, \-\-header].
.PP
\fIluksKillSlot\fR <device> <key slot number>
.IP
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].
+\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset,
+\-\-keyfile\-size, \-\-header].
\fBWARNING:\fR If you read the passphrase from stdin
(without further argument or with '-' as argument
-to \-\-key-file), batch-mode (-q) will be implicitely
+to \-\-key-file), batch-mode (\-q) will be implicitely
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
+\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.
.IP
Dump the header information of a LUKS device.
-If the \-\-dump-master-key option is used, the LUKS device master key is
+If the \-\-dump\-master\-key option is used, the LUKS device master key is
dumped instead of the keyslot info. Beware that the master key cannot be
changed and can be used to decrypt the data stored in the LUKS container
without a passphrase and even without the LUKS header. This means
erased to prevent further access. Use this option carefully.
In order to dump the master key, a passphrase has to be supplied,
-either interactively or via \-\-key-file.
+either interactively or via \-\-key\-file.
-\fB<options>\fR can be [\-\-dump-master-key, \-\-key-file,
-\-\-keyfile-offset, \-\-keyfile-size].
+\fB<options>\fR can be [\-\-dump\-master\-key, \-\-key\-file,
+\-\-keyfile\-offset, \-\-keyfile\-size, \-\-header].
-\fBWARNING:\fR If \-\-dump-master-key is used with \-\-key-file
-and the argument to \-\-key-file is '-', no validation question
+\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>
+\fIluksHeaderBackup\fR <device> \-\-header\-backup\-file <file>
.IP
Stores a binary backup of the LUKS header and keyslot area.
.br
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>
+\fIluksHeaderRestore\fR <device> \-\-header\-backup\-file <file>
.IP
Restores a binary backup of the LUKS header and keyslot area
from the specified file.
cryptsetup supports mapping loop-AES encrypted partition using
a compatibility mode.
.PP
-\fIopen\fR \-\-type loopaes <device> <name> \-\-key-file <keyfile>
+\fIopen\fR \-\-type loopaes <device> <name> \-\-key\-file <keyfile>
.br
-\fIloopaesOpen\fR <device> <name> \-\-key-file <keyfile> (\fBold syntax\fR)
+\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:
+\-\-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 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
-gpg \-\-decrypt <keyfile> | cryptsetup loopaesOpen \-\-key-file=- <device> <name>
+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\-\-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.
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].
+\fB<options>\fR can be [\-\-key\-file, \-\-key\-size, \-\-offset, \-\-skip,
+\-\-hash, \-\-readonly, \-\-allow\-discards].
.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) EXTENSION
-cryptsetup supports mapping of TrueCrypt or tcplay encrypted partition
+.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.
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 VeraCrypt device use \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).
+
\fBNOTE:\fR Activation with \fBtcryptOpen\fR is supported only for cipher chains
using LRW or XTS encryption modes.
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. Use the whole
-device not the system partition as the device parameter.
+system resides) use \fB\-\-tcrypt\-system\fR option.
+You can use partition device as the parameter (parameter must be real partition
+device, not image in file), then only this partition is mapped.
+
+If you have 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 whole base device as 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 whole device.
To use hidden header (and map hidden device, if available),
-use \fB\-\-tcrypt-hidden\fR option.
+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>.
+Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up
+a mapping <name>.
-\fB<options>\fR can be [\-\-key-file, \-\-tcrypt-hidden, \-\-tcrypt-system,
-\-\-readonly, \-\-test-passphrase].
+\fB<options>\fR can be [\-\-key\-file, \-\-tcrypt\-hidden,
+\-\-tcrypt\-system, \-\-tcrypt\-backup, \-\-readonly, \-\-test\-passphrase,
+\-\-allow-discards].
The keyfile parameter allows 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
+\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
+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].
+\fB<options>\fR can be [\-\-dump\-master\-key, \-\-key\-file,
+\-\-tcrypt\-hidden, \-\-tcrypt\-system, \-\-tcrypt\-backup].
The keyfile parameter allows combination of file content with the
passphrase and can be repeated.
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.
+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.
"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].
+\fB<options>\fR can be [\-\-cipher, \-\-key\-size, \-\-hash].
.SH OPTIONS
.TP
.B "\-\-verbose, \-v"
Run in debug mode with full diagnostic logs. Debug output
lines are always prefixed by '#'.
.TP
-.B "\-\-hash, \-h \fI<hash-spec>\fR"
-Specifies the passphrase hash for \fIopen\fR (for plain and loopaes device types).
+.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.
+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
+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.
Use \fIcryptsetup \-\-help\fR to show the defaults.
.TP
-.B "\-\-cipher, \-c \fI<cipher-spec>\fR"
+.B "\-\-cipher, \-c \fI<cipher\-spec>\fR"
Set the cipher specification string.
\fIcryptsetup \-\-help\fR shows the compiled-in defaults.
"aes-cbc-essiv:sha256" for plain dm-crypt and
"aes-xts-plain64" for LUKS.
+If a hash is part of the cipher spefification, 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
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. Ignores on input from file or stdin.
+\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
+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
+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
See section \fBNOTES ON PASSPHRASE PROCESSING\fR for more information.
.TP
-.B "\-\-keyfile-offset \fIvalue\fR"
+.B "\-\-keyfile\-offset \fIvalue\fR"
Skip \fIvalue\fR bytes at the beginning of the key file.
Works with all commands that accepts key files.
.TP
-.B "\-\-keyfile-size, \-l \fIvalue\fR"
+.B "\-\-keyfile\-size, \-l \fIvalue\fR"
Read a maximum of \fIvalue\fR bytes from the key file.
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
+to cut trailing newlines, for example. If \-\-keyfile\-offset
is also given, the size count starts after the offset.
Works with all commands that accepts key files.
.TP
-.B "\-\-new-keyfile-offset \fIvalue\fR"
+.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"
+.B "\-\-new\-keyfile\-size \fIvalue\fR"
Read a maximum of \fIvalue\fR bytes when adding
a new passphrase from key file with \fIluksAddKey\fR.
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
+When \-\-new\-keyfile\-offset is also given, reading starts
after the offset.
.TP
-.B "\-\-master-key-file"
+.B "\-\-master\-key\-file"
Use a master key stored in a file.
For \fIluksFormat\fR this
then the new header decrypts the data encrypted with the
header the master key was taken from.
+\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 exiting one.
-For \fIopen\fR this allows to open the LUKS device
+For \fIopen\fR this allows one to open the LUKS device
without giving a passphrase.
.TP
-.B "\-\-dump-master-key"
+.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.
+bypass the passphrases, see also option \-\-master\-key\-file.
.TP
-.B "\-\-use-random"
+.B "\-\-use\-random"
.TP
-.B "\-\-use-urandom"
+.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).
forever, if not enough entropy can be harvested by
the kernel.
.TP
-.B "\-\-key-slot, \-S <0-7>"
+.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,
If the given passphrase would only match a different key-slot,
the operation fails.
.TP
-.B "\-\-key-size, \-s <bits>"
+.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.
or loopaes device types.
.TP
.B "\-\-skip, \-p <number of 512 byte sectors>"
-How many sectors of the encrypted data to skip at the beginning.
+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.
-This is different from the \-\-offset options with respect to
-the sector numbers used in IV calculation.
-Using \-\-offset will shift the IV calculation by the same negative amount.
-Hence, if \-\-offset \fIn\fR, sector \fIn\fR will get a sector
-number of \fI0\fR for the IV calculation.
-Using \-\-skip causes sector \fIn\fR to also be the first sector
-of the mapped device, but with its number for IV generation is \fIn\fR.
+Hence, if \-\-offset \fIn\fR, and \-\-skip \fIs\fR, sector \fIn\fR
+(the first sector of encrypted device) will get a sector number
+of \fIs\fR for the IV calculation.
.TP
.B "\-\-readonly, \-r"
set up a read-only mapping.
.B "\-\-shared"
Creates an additional mapping for one common
ciphertext device. Arbitrary mappings are supported.
-This option is only relevant for the
+This option is only relevant for the
\fIopen \-\-type plain\fR action. Use \-\-offset, \-\-size and \-\-skip to
specify the mapped area.
.TP
-.B "\-\-iter-time, \-i <number of milliseconds>"
+.B "\-\-iter\-time, \-i <number of milliseconds>"
The number of milliseconds to spend with PBKDF2 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 "\-\-batch-mode, \-q"
+.B "\-\-batch\-mode, \-q"
Suppresses all confirmation questions. Use with care!
If the \-y option is not specified, this option also switches off
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
+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.
\fIopen\fR, \fIluksFormat\fR or \fIluksAddKey\fR.
The default is 3 tries.
.TP
-.B "\-\-align-payload <number of 512 byte sectors>"
+.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.
The UUID must be provided in the standard UUID format,
e.g. 12345678-1234-1234-1234-123456789abc.
.TP
-.B "\-\-allow-discards\fR"
+.B "\-\-allow\-discards\fR"
Allow the use of discard (TRIM) requests for device.
This option is only relevant for \fIopen\fR action.
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 no use it.
+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 "\-\-test-passphrase\fR"
+.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 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 options allows to store ciphertext
+LUKS header is stored. This options allows one to store ciphertext
and LUKS header on different devices.
-This option is only relevant for LUKS devices and can be
+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.
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
+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
arbitrary device as the ciphertext device for \fIopen\fR
with the \-\-header option. Use with care.
.TP
-.B "\-\-force-password\fR"
+.B "\-\-force\-password\fR"
Do not use password quality checking for new LUKS passwords.
This option applies only to \fIluksFormat\fR, \fIluksAddKey\fR and
first newline, i.e. '\\n'.
The input without the newline character is processed with
the default hash or the hash specified with \-\-hash.
-The has result will be truncated to the key size
+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
+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 has result will be truncated to the key size
+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
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
+\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 binary key.
-if the key file is shorter than the key, cryptsetup
+
+\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
\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
+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
+input. The \-\-keyfile\-size option can be used to limit
what is read.
\fBPassphrase processing\fR:
The default setting of one second is sufficient for most
practical cases. The only exception is a low-entropy
-passphrase used on a slow device.
+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.
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
+\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
+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.
Please attach the output of the failed command with the
\-\-debug option added.
.SH AUTHORS
-cryptsetup originally written by Christophe Saout <christophe@saout.de>
+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 rewrite and extension by Arno Wagner <arno@wagner.name>.
.SH COPYRIGHT
-Copyright \(co 2004 Christophe Saout
+Copyright \(co 2004 Jana Saout
.br
Copyright \(co 2004-2006 Clemens Fruhwirth
.br
-Copyright \(co 2009-2012 Red Hat, Inc.
+Copyright \(co 2009-2015 Red Hat, Inc.
.br
-Copyright \(co 2009-2012 Milan Broz
+Copyright \(co 2009-2015 Milan Broz
.br
-Copyright \(co 2012 Arno Wagner
+Copyright \(co 2012-2014 Arno Wagner
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 \fBhttp://code.google.com/p/cryptsetup/\fR
+The LUKS website at \fBhttps://gitlab.com/cryptsetup/cryptsetup/\fR
The cryptsetup FAQ, contained in the distribution package and
online at
-\fBhttp://code.google.com/p/cryptsetup/wiki/FrequentlyAskedQuestions\fR
+\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
-\fBhttp://code.google.com/p/cryptsetup/wiki/Specification\fR
+\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/Specification\fR
projects / platform / upstream / cryptsetup.git / blobdiff