between security and safety, as LUKS is designed for fast and
secure wiping by just overwriting header and key-slot area.
-.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>.
+\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
+Opens (creates a mapping) with <name> backed by device <device>.
-There are four operations:
+Device type can be \fIplain\fR, \fIluks\fR (default), \fIloopaes\fR
+or \fItcrypt\fR.
-\fIcreate\fR <name> <device>
-.IP
-Creates a mapping with <name> backed by device <device>.
+For backward compatibility there are \fBopen\fR command aliases:
-\fB<options>\fR can be [\-\-hash, \-\-cipher, \-\-verify-passphrase,
-\-\-key-file, \-\-keyfile-offset, \-\-key-size, \-\-offset, \-\-skip, \-\-size,
-\-\-readonly, \-\-shared, \-\-allow-discards]
+\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
-Example: 'cryptsetup create e1 /dev/sda10' 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.
+\fB<options>\fR are type specific and are described below
+for individual device types.
.PP
-\fIremove\fR <name>
+\fIclose\fR <name>
.IP
Removes the existing mapping <name> and wipes the key from kernel memory.
+
+For backward compatibility there are \fBclose\fR command aliases:
+\fBremove\fR, \fBplainClose\fR, \fBluksClose\fR, \fBloopaesClose\fR,
+\fBtcryptClose\fR (all behaves exactly the same, device type is
+determined automatically from active device).
.PP
\fIstatus\fR <name>
.IP
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>.
+
+\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,
make all data the old container permanently irretrievable, unless
you have a header backup.
.PP
-\fIluksOpen\fR <device> <name>
+\fIopen\fR \-\-type luks <device> <name>
+.br
+\fIluksOpen\fR <device> <name> (\fBold syntax\fR)
.IP
Opens the LUKS device <device> and sets up a mapping <name> after
successful verification of the supplied passphrase.
\-\-keyfile-size, \-\-readonly, \-\-test-passphrase,
\-\-allow-discards, \-\-header, \-\-key-slot, \-\-master-key-file].
.PP
-\fIluksClose\fR <name>
-.IP
-identical to \fIremove\fR.
-.PP
\fIluksSuspend\fR <name>
.IP
Suspends an active device (all IO operations will blocked
key from kernel memory. Needs kernel 2.6.19 or later.
After this operation you have to use \fIluksResume\fR to reinstate
-the encryption key and unblock the device or \fIluksClose\fR to remove
+the encryption key and unblock the device or \fIclose\fR to remove
the mapped device.
\fBWARNING:\fR never suspend the device on which the cryptsetup binary resides.
of the LUKS header already on the device and of the header backup
match. Alternatively, if there is no LUKS header on the device,
the backup will also be written to it.
-.PP
-\fIrepair\fR <device>
-.IP
-Tries to repair the LUKS device metadata if possible.
-
-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.
.SH loop-AES EXTENSION
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>.
\fB<options>\fR can be [\-\-key-file, \-\-key-size, \-\-offset, \-\-skip,
\-\-hash, \-\-readonly, \-\-allow-discards].
.PP
-\fIloopaesClose\fR <name>
-.IP
-Identical to \fIremove\fR.
-.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
+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
+(kernel af_alg and algif_skcipher modules, introduced in Linux kernel 2.6.38).
+
+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
+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
+\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. Without parameters it tries to measure few common
-configurations.
+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.
+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.
-This benchmark requires kernel userspace crypto API interface to be available
-(kernel af_alg and af_skcipher modules, introduced in Linux kernel 2.6.38).
+For testing block ciphers, this benchmark requires kernel userspace
+crypto API to be available (kernel af_alg and algif_skcipher modules,
+introduced in Linux kernel 2.6.38).
-\fB<options>\fR can be [\-\-cipher, \-\-key-size].
+\fB<options>\fR can be [\-\-cipher, \-\-key-size, \-\-hash].
.SH OPTIONS
.TP
.B "\-\-verbose, \-v"
lines are always prefixed by '#'.
.TP
.B "\-\-hash, \-h \fI<hash-spec>\fR"
-Specifies the passphrase hash for \fIcreate\fR and \fIloopaesOpen\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.
\fB"crc32"\fR as this breaks security.
Values compatible with old version of cryptsetup are
-\fB"ripemd160"\fR for \fIcreate\fR and
+\fB"ripemd160"\fR for \fIopen \-\-type plain\fR and
\fB"sha1"\fR for \fIluksFormat\fR.
Use \fIcryptsetup \-\-help\fR to show the defaults.
For \fIluksAddKey\fR this allows adding a new passphrase
without having to know an exiting one.
-For \fIluksOpen\fR this allows to open the LUKS device
+For \fIopen\fR this allows to open the LUKS device
without giving a passphrase.
.TP
.B "\-\-dump-master-key"
This option can be used for \fIluksFormat\fR,
and \fIluksAddKey\fR.
.br
-In addition, for \fIluksOpen\fR, this option selects a
+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.
See /proc/crypto for more information. Note that key-size
in /proc/crypto is stated in bytes.
-This option can be used for \fIcreate\fR or \fIluksFormat\fR. All
-other LUKS actions will use the key-size specified in the LUKS header.
+This option can be used for \fIopen \-\-type plain\fR or \fIluksFormat\fR.
+All other LUKS actions will use the key-size specified in the LUKS header.
Use \fIcryptsetup \-\-help\fR to show the compiled-in defaults.
.TP
.B "\-\-size, \-b <number of 512 byte sectors>"
Force the size of the underlying device in sectors of 512 bytes.
-This option is only relevant for the \fIcreate\fR and \fIresize\fR
+This option is only relevant for the \fIopen\fR and \fIresize\fR
actions.
.TP
.B "\-\-offset, \-o <number of 512 byte sectors>"
Start offset in the backend device in 512-byte sectors.
-This option is only relevant for the \fIcreate\fR and \fIloopaesOpen\fR
-actions.
+This option is only relevant for the \fIopen\fR action with plain
+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.
-This option is only relevant for \fIcreate\fR and \fIloopaesOpen\fR action.
+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.
Creates an additional mapping for one common
ciphertext device. Arbitrary mappings are supported.
This option is only relevant for the
-\fIcreate\fR action. Use \-\-offset, \-\-size and \-\-skip to
+\fIopen \-\-type plain\fR action. Use \-\-offset, \-\-size and \-\-skip to
specify the mapped area.
.TP
.B "\-\-iter-time, \-i <number of milliseconds>"
.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 \fIcreate\fR, \fIluksOpen\fR, \fIluksFormat\fR
-or \fIluksAddKey\fR. It has no effect if used in conjunction
-with \-\-key-file.
+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,
How often the input of the passphrase shall be retried.
This option is relevant
every time a passphrase is asked, for example for
-\fIcreate\fR, \fIluksOpen\fR, \fIluksFormat\fR
-or \fIluksAddKey\fR. The default is 3 tries.
+\fIopen\fR, \fIluksFormat\fR or \fIluksAddKey\fR.
+The default is 3 tries.
.TP
.B "\-\-align-payload <number of 512 byte sectors>"
Align payload at a boundary of \fIvalue\fR 512-byte sectors.
.TP
.B "\-\-allow-discards\fR"
Allow the use of discard (TRIM) requests for device.
-This option is only relevant for \fIcreate\fR, \fIluksOpen\fR
-and \fIloopaesOpen\fR.
+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
.TP
.B "\-\-test-passphrase\fR"
Do not activate device, just verify passphrase.
-This option is only relevant for \fIluksOpen\fR.
+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
and LUKS header on different devices.
This option is only relevant for LUKS devices and can be
-used with the \fIluksFormat\fR, \fIluksOpen\fR, \fIluksSuspend\fR,
+used with the \fIluksFormat\fR, \fIopen\fR, \fIluksSuspend\fR,
\fIluksResume\fR, \fIstatus\fR and \fIresize\fR commands.
For \fIluksFormat\fR with a file name as argument to \-\-header,
\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 \fIluksOpen\fR
+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.
+
+For more info about password quality check, see manual page
+for \fBpwquality.conf(5)\fR.
+.TP
.B "\-\-version"
Show the program version.
.TP
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 luksOpen will take longer to
+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.
.br
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
projects / platform / upstream / cryptsetup.git / blobdiff