.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.
-.SH ACTIONS
-These strings are valid for \fB<action>\fR, followed by their \fB<action args>\fR:
\fIcreate\fR <name> <device>
.IP
creates a mapping with <name> backed by device <device>.
\fB<options>\fR can be [\-\-hash, \-\-cipher, \-\-verify-passphrase,
-\-\-key-file, \-\-key-size, \-\-offset, \-\-skip, \-\-readonly]
+\-\-key-file, \-\-key-size, \-\-offset, \-\-skip, \-\-size, \-\-readonly]
.PP
\fIremove\fR <name>
.IP
.IP
opens the loop-AES <device> and sets up a mapping <name>.
-N.B. If keyfile is in GPG encrypted format, you have to use
+N.B. If key file is in GPG encrypted format, you have to use
\-\-key-file=- and decrypt it before use.
-gpg --decrypt <keyfile> | cryptsetup loopaesOpen \-\-key-file=- <device> <name>
+gpg \-\-decrypt <keyfile> | cryptsetup loopaesOpen \-\-key-file=- <device> <name>
-Use \-\-key-file to specify proper key length, default compiled-in
-parameters are visible in \-\-help output.
+Use \fB\-\-key-file\fR to specify proper key length, default compiled-in
+parameters are visible in \fB\-\-help\fR output.
-\fB<options>\fR can be [\-\-key-file, \-\-key-size, \-\-offset, \-\-readonly].
+Use \fB\-\-offset\fR to specify device offset. Note the units need to be
+specified in 512 bytes 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\-\-hash\fR to override hash function for password hashing
+(otherwise it is detected according to key size).
+
+\fB<options>\fR can be [\-\-key-file, \-\-key-size, \-\-offset, \-\-skip,
+\-\-hash, \-\-readonly].
.PP
\fIloopaesClose\fR <name>
.IP
Run in debug mode with full diagnostic logs.
.TP
.B "\-\-hash, \-h"
-For \fIcreate\fR action specifies hash to use for password hashing.
+For \fIcreate\fR and \fIloopaesOpen\fR action specifies hash to use for password hashing.
For \fIluksFormat\fR action specifies hash used in LUKS key setup scheme
and volume key digest.
If not changed, the default is for plain dm-crypt and LUKS mappings
"aes-cbc-essiv:sha256".
-For pre-2.6.10 kernels, use "aes-plain" as they don't understand
-the new cipher spec strings. To use ESSIV, use "aes-cbc-essiv:sha256".
-
For XTS mode, kernel version 2.6.24 or more recent is required.
-Use "aes-xts-plain" cipher specification and set key size to 256
+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.
.TP
.B "\-\-verify-passphrase, \-y"
query for passwords twice. Useful when creating a (regular) mapping
See section \fBNOTES ON PASSWORD PROCESSING\fR for more information.
.TP
.B "\-\-keyfile-size, \-l \fIvalue\fR"
-Limits read from keyfile to \fIvalue\fR bytes.
-Usable together with all comands using key file.
+Limits read from key file to \fIvalue\fR bytes.
+Usable together with all commands using key file.
.TP
.B "\-\-new-keyfile-size \fIvalue\fR"
-Limits read from new keyfile to \fIvalue\fR bytes in \fIluksAddKey\fR when
+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.
.TP
.B "\-\-master-key-file"
.TP
.B "\-\-offset, \-o"
start offset in the backend device (in 512-byte sectors).
-This option is only relevant for \fIcreate\fR action.
+This option is only relevant for \fIcreate\fR and \fIloopaesOpen\fR action.
.TP
.B "\-\-skip, \-p"
how many sectors of the encrypted data to skip at the beginning.
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 action.
+This option is only relevant for \fIcreate\fR and \fIloopaesOpen\fR action.
.TP
.B "\-\-readonly"
set up a read-only mapping.
.TP
.B "\-\-version"
Show the version.
-.SH NOTES ON PASSWORD PROCESSING
+.SH RETURN CODES
+Crypsetup returns 0 on success or non-zero 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 (so using
-e.g. /dev/random as stdin will not work), with the trailing
-newline stripped.
-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.
+\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.
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
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
+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.
See \fPurandom(4)\fR for more information.
projects / platform / upstream / cryptsetup.git / blobdiff