From ArchWiki
Revision as of 13:38, 28 September 2012 by Nonix (talk | contribs) (Man page content: added notes on RNG)
Jump to: navigation, search


luksFormat / luksAddKey Options

# cryptsetup -c aes-xts-plain -s <key size> -h sha512 -i 5000 luksFormat <device> --use-random
available options default comment example comment
--cipher, -c aes-cbc-essiv:sha256 CBC with ESSIV. aes-xts-plain XTS. For volumes >2TiB use aes-xts-plain64 (requires kernel >= 2.6.33)
--key-size, -s 256 AES-256 512 XTS splits the supplied key into fraternal twins. For AES-256 key size must be 512.
--hash, -h sha1 Hash algorithm used for PBKDF2. sha512
--iter-time, -i 1000 Number of milliseconds to spend with PBKDF2 passphrase processing. 5000 Using a hash stronger than sha1 results in less iterations if iter-time is not increased.
--use-random (luksFormat only) --use-urandom /dev/urandom is used as randomness source for the (long-term) volume master key. Look up Random. --use-random Avoid generating an insecure master key if low on entropy. Will block if the entropy pool is used up.
--verify-passphrase, -y for luksFormat and luksAddKey no need to type

Check results

# cryptsetup luksDump /dev/<drive>




Wikipedia:Disk_encryption_theory#Cipher-block_chaining_.28CBC.29 CBC



XEX-based tweaked-codebook mode with ciphertext stealing

Man page content

--cipher, -c <cipher-spec>

Set the cipher specification string. cryptsetup --help 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.

For volumes >2TiB and kernels >= 2.6.33 use "plain64". "Plain" uses 64 bit sector numbers, with the upper 32 bit set to zero. This means that on volumes larger than 2TiB, the IV repeats, creating a vulnerability that potentially leaks some data. To avoid this, use "plain64", which uses the full sector number up to 64 bit. Note that "plain64" requires a kernel >= 2.6.33. Also note that "plain64" is backwards compatible for volume sizes <= 2TiB, but not for those > 2TiB. Finally, "plain64" does not cause any performance penalty compared to "plain".

--key-size, -s <bits>

Sets key size in bits. The argument has to be a multiple of 8. The possible key-sizes are limited by the cipher and mode used. See /proc/crypto for more information. Note that key-size in /proc/crypto is stated in bytes. This option can be used for create or luksFormat. All other LUKS actions will use the key-size specified in the LUKS header. Use cryptsetup --help to show the compiled-in defaults.

--hash, -h <hash-spec>

Specifies the passphrase hash for create and loopaesOpen. Specifies the hash used in the LUKS key setup scheme and volume key digest for luksFormat. The specified hash name is passed to the compiled-in crypto backend. Different backends may support different hashes. For luksFormat, the hash algorithm must provide at least 160 bits of output, which excludes, e.g., MD5. Do not use a non-crypto hash like "crc32" as this breaks security. Values compatible with old version of cryptsetup are "ripemd160" for create and "sha1" for luksFormat. Use cryptsetup --help to show the defaults.

--iter-time, -i <number of milliseconds>

default:0=1000 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 luksFormat or luksAddKey. Specifying 0 as parameter selects the compiled-in default.


For luksFormat these options define which kernel random number generator will be used to create the master key (which is a long-term key). You may want to make sure to use /dev/random (by specifying --use-random on luksFormat) as randomness source for the volume master key to avoid being potentially insecure in an entropy-starved situation. WARNING: 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.

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 --use-random and --use-urandom options. Using /dev/random on a system without enough entropy sources can cause luksFormat 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 urandom(4) for more information.