-.TH CRYPTSETUP "8" "" "cryptsetup" "Maintenance Commands"
+.TH CRYPTSETUP "8" "May 2012" "cryptsetup" "Maintenance Commands"
.SH NAME
-cryptsetup - setup cryptographic volumes for dm-crypt (including LUKS extension)
+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.
-.SH PLAIN MODE
-For basic (plain) dm-crypt mappings, there are four operations.
-
-\fIcreate\fR <name> <device>
+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.
+.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 backup of an
+encrypted volume.
+
+\fBCharacter encoding:\fR If you enter a
+passphrase with special symbols, the passphrase can change
+depending 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 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>
.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, \-\-key-size, \-\-offset, \-\-skip, \-\-size, \-\-readonly, \-\-shared,
-\-\-allow-discards]
+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)
+.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.
.PP
-\fIremove\fR <name>
+\fIclose\fR <name>
.IP
-removes an existing mapping <name>.
+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).
.PP
\fIstatus\fR <name>
.IP
-reports the status for the mapping <name>.
+Reports the status for the mapping <name>.
.PP
\fIresize\fR <name>
.IP
-resizes an active mapping <name>.
+Resizes an active mapping <name>.
-If \-\-size (in sectors) is not specified, the size of the underlying block device is used.
-.SH LUKS EXTENSION
-LUKS, Linux Unified Key Setup, is a standard for hard disk encryption.
-It standardizes a partition header as well as the format of the bulk data.
-LUKS can manage multiple passwords that can be individually revoked and
-effectively scrubbed from persistent media, and that are protected
-against dictionary attacks with PBKDF2.
+If \-\-size (in sectors) is not specified, the size of the
+underlying block device 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.
+.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 (created), 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
+Creates a mapping with <name> backed by device <device>.
-Each password, usually called a
+\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
+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.
+
+Each passphrase, also called a
.B key
-in this document, is associated with a slot, of which there are typically 8.
+in this document, is associated with one of 8 key-slots.
Key operations that do not specify a slot affect the first slot
-matching the supplied key.
+that matches the supplied passphrase or the first empty slot if
+a new passphrase is added.
-These are valid LUKS actions:
+The following are valid LUKS actions:
\fIluksFormat\fR <device> [<key file>]
.IP
-initializes a LUKS partition and sets the initial key, either via prompting or via <key file>.
+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 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.
\fB<options>\fR can be [\-\-cipher, \-\-verify-passphrase, \-\-key-size,
\-\-key-slot, \-\-key-file (takes precedence over optional second argument),
-\-\-keyfile-size, \-\-use-random | \-\-use-urandom, \-\-uuid, \-\-master-key-file].
-.PP
-\fIluksOpen\fR <device> <name>
-.IP
-opens the LUKS partition <device> and sets up a mapping <name> after
-successful verification of the supplied key material
-(either via key file by \-\-key-file, or via prompting).
+\-\-keyfile-offset, \-\-keyfile-size, \-\-use-random | \-\-use-urandom,
+\-\-uuid, \-\-master-key-file].
-\fB<options>\fR can be [\-\-key-file, \-\-keyfile-size, \-\-readonly, \-\-allow-discards,
-\-\-header, \-\-key-slot, \-\-master-key-file].
+\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
-\fIluksClose\fR <name>
+\fIopen\fR \-\-type luks <device> <name>
+.br
+\fIluksOpen\fR <device> <name> (\fBold syntax\fR)
.IP
-identical to \fIremove\fR.
+Opens the LUKS device <device> and sets up a mapping <name> after
+successful verification of the supplied passphrase.
+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].
.PP
\fIluksSuspend\fR <name>
.IP
-suspends active device (all IO operations are frozen) and wipes encryption
-key from kernel. Kernel version 2.6.19 or later is required.
+Suspends an active device (all IO operations will blocked
+and accesses to the device will wait indefinitely)
+and wipes the encryption
+key from kernel memory. Needs kernel 2.6.19 or later.
-After that operation you have to use \fIluksResume\fR to reinstate
-encryption key (and resume device) or \fIluksClose\fR to remove mapped device.
+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 try to suspend device where is the cryptsetup binary itself.
+\fBWARNING:\fR never suspend the device on which the cryptsetup binary resides.
\fB<options>\fR can be [\-\-header].
.PP
\fIluksResume\fR <name>
.IP
-Resumes suspended device and reinstates encryption key. You will need provide passphrase
-identical to \fIluksOpen\fR command (using prompting or key file).
+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]
.PP
-\fIluksAddKey\fR <device> [<new key file>]
+\fIluksAddKey\fR <device> [<key file with new key>]
.IP
-add a new key file/passphrase. An existing passphrase or key file
-(via \-\-key-file) must be supplied.
-The key file with the new material is supplied as a positional argument.
-
-\fB<options>\fR can be [\-\-key-file, \-\-keyfile-size, \-\-new-keyfile-size, \-\-key-slot,
-\-\-master-key-file].
+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.
+
+\fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset,
+\-\-keyfile-size, \-\-new-keyfile-offset,
+\-\-new-keyfile-size, \-\-key-slot, \-\-master-key-file].
.PP
-\fIluksRemoveKey\fR <device> [<key file>]
+\fIluksRemoveKey\fR <device> [<key file with passphrase to be removed>]
.IP
-remove supplied key or key file from LUKS device in the manner of \fIluksKillSlot\fR.
+Removes the supplied passphrase from the LUKS device. The
+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]
+
+\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
+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
-change existing key file or passphrase. An existing passphrase
-or key file (via \-\-key-file) must be supplied.
-The key file with the new material is supplied as a positional argument.
-
-If no key slot is specified (and there is still free key slot on device)
-new slot is allocated before the old is purged.
-
-If \fB\-\-key\-slot\fR option is specified (or there is no free slot)
-command will overwrite existing slot.
-
-\fBWARNING:\fR Be sure you have another slot active or header backup
-when using explicit key slot (so you can unlock the device even after
-possible media failure during slot swap).
-
-\fB<options>\fR can be [\-\-key-file, \-\-keyfile-size,\-\-new-keyfile-size,
-\-\-key-slot].
+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].
.PP
\fIluksKillSlot\fR <device> <key slot number>
.IP
-wipe key with number <key slot> from LUKS device. A remaining passphrase or
-key file (via \-\-key-file) must be supplied.
-
-\fB<options>\fR can be [\-\-key-file, \-\-keyfile-size].
+Wipe the key-slot number <key slot> from the LUKS device. 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].
+
+\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
+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
\fIluksUUID\fR <device>
.IP
-print UUID, if <device> has a LUKS header.
-
-set new UUID if \fI\-\-uuid\fR option is specified.
+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 partition. Otherwise, false.
+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.
.PP
\fIluksDump\fR <device>
.IP
-dumps the header information of a LUKS partition.
-
-If \-\-dump-master-key option is used, the volume (master) key is dumped
-instead of keyslot info.
+Dump the header information of a LUKS device.
-Because this information can be used to access encrypted device without
-passphrase knowledge (even without LUKS header) use this option
-very carefully.
+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
+that if the master key is compromised, the whole device has to be
+erased to prevent further access. Use this option carefully.
-Dump with volume key (either printed or stored to file) should be always
-stored encrypted and on safe place.
+In order to dump the master key, a passphrase has to be supplied,
+either interactively or via \-\-key-file.
-LUKS passphrase or key file is required for volume key dump.
+\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-size].
+\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 binary backup of LUKS header and keyslot areas.
-
-\fBWARNING:\fR Please note that with this backup file (and old passphrase
-knowledge) you can decrypt data even if old passphrase was wiped from real device.
-
-Also note that anti-forensic splitter is not used during manipulation with backup file.
+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 binary backup of LUKS header and keyslot areas from specified file.
+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 All the keyslot areas are overwritten, only active keyslots
-form backup file are available after issuing this command.
+\fBWARNING:\fR Header and keyslots will be replaced, only
+the passphrases from the backup will work afterwards.
-This command allows restoring header if device do not contain LUKS header
-or if the master key size and data offset in LUKS header on device match the backup file.
-.PP
-For more information about LUKS, see
-\fBhttp://code.google.com/p/cryptsetup/wiki/Specification\fR
+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.
.SH loop-AES EXTENSION
-cryptsetup supports mapping of loop-AES encrypted partition using
-compatible dm-crypt mode.
+cryptsetup supports mapping loop-AES encrypted partition using
+a compatibility mode.
.PP
-\fIloopaesOpen\fR <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)
.IP
-opens the loop-AES <device> and sets up a mapping <name>.
+Opens the loop-AES <device> and sets up a mapping <name>.
-N.B. If key file is in GPG encrypted format, you have to use
-\-\-key-file=- and decrypt it before use.
+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>
-Use \fB\-\-key-file\fR to specify proper key length, default compiled-in
-parameters are visible in \fB\-\-help\fR output.
+Use \fB\-\-keyfile-size\fR to specify the proper key length if needed.
-Use \fB\-\-offset\fR to specify device offset. Note the units need to be
-specified in 512 bytes sectors.
+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 IV offset. If original device used offset
-and not used it in IV sector calculations, you have to explicitly use
-\fB\-\-skip 0\fR in addition to offset parameter.
+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 hash function for password hashing
-(otherwise it is detected according to key size).
+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].
.PP
-\fIloopaesClose\fR <name>
+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
+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).
+
+\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. Use the whole
+device not the system partition as the device parameter.
+
+To use hidden header (and map hidden device, if available),
+use \fB\-\-tcrypt-hidden\fR option.
+.PP
+\fIopen\fR \-\-type tcrypt <device> <name>
+.br
+\fItcryptOpen\fR <device> <name> (\fBold syntax\fR)
.IP
-identical to \fIremove\fR.
+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].
+
+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.
.PP
-For more information about loop-AES, see \fBhttp://loop-aes.sourceforge.net\fR
+\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].
+
+The keyfile parameter allows combination of file content with the
+passphrase and can be repeated.
+.PP
+See also \fBhttp://www.truecrypt.org\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 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.
+
+\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 verbose messages.
+Print more information on command execution.
.TP
.B "\-\-debug"
-Run in debug mode with full diagnostic logs.
+Run in debug mode with full diagnostic logs. Debug output
+lines are always prefixed by '#'.
.TP
-.B "\-\-hash, \-h"
-For \fIcreate\fR and \fIloopaesOpen\fR action specifies hash to use for password hashing.
+.B "\-\-hash, \-h \fI<hash-spec>\fR"
+Specifies the passphrase hash for \fIopen\fR (for plain and loopaes device types).
-For \fIluksFormat\fR action specifies hash used in LUKS key setup scheme
-and volume key digest.
+Specifies the hash used in the LUKS key setup scheme and volume key digest
+for \fIluksFormat\fR.
-\fBWARNING:\fR setting hash other than \fBsha1\fR causes LUKS device
-incompatible with older version of cryptsetup.
+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.
-The hash string is passed to libgcrypt, so all hash algorithms are supported
-(for \fIluksFormat\fR algorithm must provide at least 20 byte long hash).
-Default is set during compilation, compatible values with old version of cryptsetup are
-\fB"ripemd160"\fR for \fIcreate\fR action and \fB"sha1"\fR for \fIluksFormat\fR.
+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 defaults.
+Use \fIcryptsetup \-\-help\fR to show the defaults.
.TP
-.B "\-\-cipher, \-c"
-set cipher specification string.
-
-Default mode is configurable during compilation,
-you can see compiled-in default using \fIcryptsetup \-\-help\fR.
-If not changed, the default is for plain dm-crypt and LUKS mappings
-"aes-cbc-essiv:sha256".
-
-For XTS mode, kernel version 2.6.24 or more recent is required.
-Use "aes-xts-plain64" cipher specification and set key size to 256
-(or 512) bits (see \-s option).
-Note that plain64 IV (Initialization Vector) is available since kernel version 2.6.33
-and it is full 64bit version of plain IV. For more info please see FAQ.
+.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 both plain dm-crypt and LUKS.
+
+For XTS mode (a possible future default), use "aes-xts-plain"
+or better "aes-xts-plain64"
+as cipher specification and 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"
-query for passwords twice. Useful when creating a (regular) mapping
-for the first time, or when running \fIluksFormat\fR.
-
-Password verification option is ignored if requested on non terminal
-input (like pipe of file).
+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.
.TP
-.B "\-\-key-file, \-d"
-use file as key material.
+.B "\-\-key-file, \-d \fIname\fR"
+Read the passphrase from file.
-With LUKS, key material supplied in key files via \-d are always used
-for existing passphrases, except in \fIluksFormat\fR action where
-\-d is equivalent to positional key file argument.
+If the name given is "-", then the passphrase will be read from stdin.
+In this case, reading will not stop at newline characters.
-If you want to set a new key via a key file, you have to use
-a positional arg to \fIluksAddKey\fR.
+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 the key file is "-", stdin will be used. With the "-" key file
-reading will not stop when new line character is detected.
+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 PASSWORD PROCESSING\fR for more information.
+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 accepts key files.
.TP
.B "\-\-keyfile-size, \-l \fIvalue\fR"
-Limits read from key file to \fIvalue\fR bytes.
-Usable together with all commands using key file.
+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
+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"
+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"
-Limits read from new key file to \fIvalue\fR bytes in \fIluksAddKey\fR when
-adding new key file. Default is exhaustive read from key file.
+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
+after the offset.
.TP
.B "\-\-master-key-file"
-Use pre-generated master key stored in file. For \fIluksFormat\fR it allows
-LUKS header reformatting with the same master key (if all other parameters
-are the same existing encrypted data remains intact).
+Use a master key stored in a file.
-For \fIluksAddKey\fR it allows adding new passphrase with only master key knowledge.
+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.
-For \fIluksOpen\fR it allows to open the LUKS device with only master key knowledge.
+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
+without giving a passphrase.
.TP
.B "\-\-dump-master-key"
-For \fIluksDump\fR it allows LUKS header dump including volume (master) key.
-Use with care (this information allows access to device without passphrase knowledge).
-
-See \fIluksDump\fR for more info.
+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 "\-\-use-random"
.TP
.B "\-\-use-urandom"
-For \fIluksFormat\fR it defines which kernel random number generator will
-be used for long-term key (volume key).
-
-See \fBNOTES ON RNG\fR for more information. Use \fIcryptsetup \-\-help\fR
-to show default RNG.
+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"
+.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, \fIluksOpen\fR and \fIluksAddKey\fR.
+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"
-set key size in bits.
-
-Has to be a multiple of 8 bits. The key size is limited by the used cipher.
+.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 output of /proc/crypto for more information.
+See /proc/crypto for more information. Note that key-size
+in /proc/crypto is stated in bytes.
-Can be used for \fIcreate\fR or \fIluksFormat\fR, all other LUKS actions
-will use key-size specified by the LUKS header.
-Default is set during compilation, if not changed it is 256 bits.
-
-Use \fIcryptsetup \-\-help\fR to show defaults.
+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"
-force the size of the underlying device in sectors.
-This option is only relevant for \fIcreate\fR and \fIresize\fR action.
+.B "\-\-size, \-b <number of 512 byte sectors>"
+Force the size of the underlying device in sectors of 512 bytes.
+This option is only relevant for the \fIopen\fR and \fIresize\fR
+actions.
.TP
-.B "\-\-offset, \-o"
-start offset in the backend device (in 512-byte sectors).
-This option is only relevant for \fIcreate\fR and \fIloopaesOpen\fR action.
+.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.
.TP
-.B "\-\-skip, \-p"
-how many sectors of the encrypted data to skip at the beginning.
-This is different from the \-\-offset options with respect to IV calculations.
+.B "\-\-skip, \-p <number of 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 be the first sector
-on the mapping with IV \fI0\fR. Using \-\-skip would have resulted in sector
-\fIn\fR being the first sector also, but with IV \fIn\fR.
-This option is only relevant for \fIcreate\fR and \fIloopaesOpen\fR action.
+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.
.TP
-.B "\-\-readonly"
+.B "\-\-readonly, \-r"
set up a read-only mapping.
.TP
.B "\-\-shared"
-create another non-overlapping mapping to one common ciphertext device,
-e.g. to create hidden device inside another encrypted device.
-This option is only relevant for \fIcreate\fR action.
-Use \-\-offset, \-\-size and \-\-skip to specify mapped area.
+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 "\-\-iter-time, \-i"
-The number of milliseconds to spend with PBKDF2 password processing.
-This option is only relevant to the LUKS operations as
-\fIluksFormat\fR or \fIluksAddKey\fR.
-Note that 0 means default.
+.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"
-Do not ask for confirmation. Use with care!
+Suppresses all confirmation questions. Use with care!
-If \-y option is not specified, batch mode option also switches off
-passphrase verification for \fIluksFormat\fR.
+If the \-y option is not specified, this option also switches off
+the passphrase verification for \fIluksFormat\fR.
.TP
-.B "\-\-timeout, \-t"
-The number of seconds to wait before timeout. This option is relevant every
-time a password is asked, like \fIcreate\fR, \fIluksOpen\fR, \fIluksFormat\fR
-or \fIluksAddKey\fR. It has no effect if used in conjunction with \-\-key-file.
+.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 password is asked, like \fIcreate\fR, \fIluksOpen\fR, \fIluksFormat\fR
-or \fIluksAddKey\fR. The default is 3 tries.
+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=\fIvalue\fR"
+.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 topology info provided by kernel
-for underlying device to get optimal alignment.
-If not available (or calculated value is multiple of default) data is by
-default aligned to 1 MiB boundary (2048 512-byte sectors).
+If not specified, cryptsetup tries to use the topology info
+provided by kernel for the underlying device to get 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 detached LUKS header it specifies offset on data device.
-See also \-\-header option.
+For a detached LUKS header this option specifies the offset on the
+data device. See also the \-\-header option.
.TP
.B "\-\-uuid=\fIUUID\fR"
-Use provided \fIUUID\fR in \fIluksFormat\fR command instead of generating
-new one or change existing UUID in \fIluksUUID\fR command.
+Use the provided \fIUUID\fR for the \fIluksFormat\fR command
+instead of generating new one. Changes the existing UUID when
+used with the \fIluksUUID\fR command.
-The UUID must be provided in standard UUID format
-(e.g. 12345678-1234-1234-1234-123456789abc).
+The UUID must be provided in the standard UUID format,
+e.g. 12345678-1234-1234-1234-123456789abc.
.TP
.B "\-\-allow-discards\fR"
-Allow using of discards (TRIM) requests for device.
-This option is only relevant for \fIcreate\fR, \fIluksOpen\fR or \fIloopaesOpen\fR.
-
-\fBWARNING:\fR Assess the specific security risks carefully before enabling this
-option. For example, allowing discards on encrypted devices may lead to the leak
-of information about the ciphertext device (filesystem type, used space etc.)
-if the discarded blocks can be located easily on the device later.
-
-Kernel version 3.1 or more recent is required.
-For older versions is the option ignored.
+Allow the use of discard (TRIM) requests for 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 no use it.
+
+A kernel version of 3.1 or later is needed. For earlier kernels
+this option is ignored.
+.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"
-Set detached (separated) metadata device or file with LUKS header.
+.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
+and LUKS header on different devices.
-This options allows separation of ciphertext device and on-disk metadata header.
+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.
-This option is only relevant for LUKS devices and can be used in \fIluksFormat\fR,
-\fIluksOpen\fR, \fIluksSuspend\fR, \fIluksResume\fR, \fIstatus\fR and
-\fIresize\fR commands.
+For \fIluksFormat\fR with a file name as argument to \-\-header,
+it has to exist and be large enough to contain the LUKS header.
+See the cryptsetup FAQ for header size calculation.
-If used with \fIluksFormat\fR the \-\-align-payload option is taken
+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.
-For other commands with separated metadata device you have to always specify
-path to metadata device (not to the ciphertext device).
+\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 "\-\-force-password\fR"
+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.
-\fBWARNING:\fR There is no possible check that specified ciphertext device
-is correct if on-disk header is detached. Use with care.
+For more info about password quality check, see manual page
+for \fBpwquality.conf(5)\fR.
.TP
.B "\-\-version"
-Show the version.
+Show the program version.
+.TP
+.B "\-\-usage"
+Show short option help.
+.TP
+.B "\-\-help, \-?"
+Show help text and default parameters.
.SH RETURN CODES
-Crypsetup returns 0 on success or non-zero on error.
+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 PASSWORD PROCESSING FOR PLAIN MODE
-\fBFrom a terminal\fR: Password processing is new-line sensitive,
-meaning the reading will stop after encountering \\n.
-It will process the read material (without newline) with the default
-hash or the hash given by \-\-hash.
-After hashing, it will be cropped to the key size given by \-s.
-
-\fBFrom stdin\fR: Reading will continue until EOF (or until
-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 or can be overwrittten
-using \-\-keysfile-size option.
-
-After that the read data will be hashed with the default hash
-or the hash given by \-\-hash and the result will be cropped
-to the keysize given by \-s.
-
-If "plain" is used as an argument to the hash option, the input
-data will not be hashed.
-Instead, it will be zero padded (if shorter than the keysize) or
-truncated (if longer than the keysize) and used directly as the key.
+.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 has 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 has 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 keysize.
+less than the key size.
-\fBFrom a key file\fR: It will be cropped to the size given by \-s.
-If there is insufficient key material in the key file, cryptsetup
+\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
will quit with an error.
-If \-\-key-file=- is used for reading the key from stdin, no
-trailing newline is stripped from the input. Without that option,
-cryptsetup strips trailing newlines from stdin input.
-.SH NOTES ON PASSWORD PROCESSING FOR LUKS
-LUKS uses PBKDF2 to protect against dictionary attacks (see RFC 2898).
-
-LUKS will always do an exhaustive password reading.
-Hence, password can not be read from /dev/random, /dev/zero or any
-other stream that does not terminate.
-To prevent exhausting of system memory, cryptsetup limits
-maximum key file size. Compiled-in default is displayed in \-\-help
-output. You can limit reads from key file using \-\-key-size option,
-this option takes precedence over compiled-in default.
-
-For any password creation action (luksAddKey, or luksFormat),
-the user may specify how much the time the password processing
-should consume. Increasing the time will lead to a more secure
-password, but also will take luksOpen longer to complete.
-The default setting of one second is sufficient for good security.
-.SH INCOHERENT BEHAVIOUR FOR INVALID PASSWORDS/KEYS
-LUKS checks for a valid password or key when an encrypted partition
-is unlocked. Thus the luksOpen action fails with invalid password
-or key, contrary to the plain dm-crypt create action.
-
-Please also be sure that you are using the same keyboard and
-language setting as during device format.
+.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 second is sufficient for most
+practical cases. The only exception is a low-entropy
+passphrase used on a slow device.
+.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 \-\-hash option all algorithms supported by gcrypt library are available.
-.SH NOTES ON PASSWORDS
-Mathematics can't be bribed. Make sure you keep your passwords safe.
+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 (or after being) blue, your brain refuses to cooperate.
-These fallbacks are possible with LUKS, as it's only possible with LUKS
-to have multiple passwords.
-.SH NOTES ON RNG
-Random Number Generator (RNG) used in cryptsetup always uses kernel RNG without
-any modifications or additions to data stream procudes by kernel (like internal
-random pool operations or mixing with the other random sources).
-
-There are two types of randomness cryptsetup/LUKS needs. One type (which always
-uses /dev/urandom) is used for salt, AF splitter and for wiping removed
-keyslot.
-
-Second type is used for 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 system without enough entropy sources
-can cause \fPluksFormat\fR to block until the requested amount of random data is gathered.
+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 NOTES ON LOOPBACK DEVICE USE
-Cryptsetup is usually used directly over block device (like disk partition or LVM volume).
-However if the device argument is file, cryptsetup tries to allocate loopback device
-and map it into this file. This mode requires Linux kernel 2.6.25 or more recent which
-supports loop autoclear flag (loop device is cleared on last close automatically).
-
-When device mapping is active, you can see loop backing file in status command output.
-Also see losetup(8).
-.SH AUTHORS
-cryptsetup is written by Christophe Saout <christophe@saout.de>
-.br
-LUKS extensions, and man page by Clemens Fruhwirth <clemens@endorphin.org>
+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 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 DEPRECATED ACTIONS
.PP
The \fIreload\fR action is no longer supported.
The \fIluksDelKey\fR was replaced with \fIluksKillSlot\fR.
.PP
.SH REPORTING BUGS
-Report bugs to <dm-crypt@saout.de> or Issues section on LUKS website.
-Please attach output of failed command with added \-\-debug option.
+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 Christophe Saout <christophe@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 Christophe Saout
.br
Copyright \(co 2004-2006 Clemens Fruhwirth
.br
-Copyright \(co 2009-2011 Red Hat, Inc.
+Copyright \(co 2009-2012 Red Hat, Inc.
+.br
+Copyright \(co 2009-2012 Milan Broz
+.br
+Copyright \(co 2012 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
-LUKS website, \fBhttp://code.google.com/p/cryptsetup/\fR
+The LUKS website at \fBhttp://code.google.com/p/cryptsetup/\fR
+
+The cryptsetup FAQ, contained in the distribution package and
+online at
+\fBhttp://code.google.com/p/cryptsetup/wiki/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
projects / platform / upstream / cryptsetup.git / blobdiff