CRYPTTAB(5) | cryptsetup manual | CRYPTTAB(5) |
crypttab - static information about encrypted filesystems
The file /etc/crypttab contains descriptive information about encrypted devices. crypttab is only read by programs (e.g. cryptdisks_start and cryptdisks_stop), and not written; it is the duty of the system administrator to properly create and maintain this file. crypttab entries are treated sequentially, so their order matters (dependencies need to listed first).
Each encrypted device is described on a separate line. Fields on each line are separated by tabs or spaces. Lines starting with '#' are comments, and blank lines are ignored. Octal sequences \0num within a field are decoded, which can be used for values containing spaces or special characters. A backslash which doesn't start an octal sequence yields undefined behavior.
The first field, target, describes the mapped device name. It must be a plain filename without any directory components. A mapped device which encrypts/decrypts data to/from the source device will be created at /dev/mapper/target by cryptsetup.
The second field, source device, describes either the block special device or file that contains the encrypted data. Instead of giving the source device explicitly, the UUID (resp. LABEL, PARTUUID and PARTLABEL) is supported as well, using “UUID=<uuid>” (resp. “LABEL=<label>”, “PARTUUID=<partuuid>” and “PARTLABEL=<partlabel>”).
The third field, key file, describes the file to use as a key for decrypting the data of the source device. In case of a keyscript, the value of this field is given as argument to the keyscript. Note that the entire key file will be used as the passphrase; the passphrase must not be followed by a newline character.
It can also be a device name (e.g. /dev/urandom), note however that LUKS requires a persistent key and therefore does not support random data keys.
If the key file is the string none, a passphrase will be read interactively from the console. In this case, the options check, checkargs and tries may be useful.
The fourth field, options, is an optional comma-separated list of options and/or flags describing the device type (luks, tcrypt, bitlk, fvault2, or plain which is also the default) and cryptsetup options associated with the encryption process. The supported options are described below. For plain dm-crypt devices the cipher, hash and size options are required. Some options can be changed on active mappings using cryptsetup refresh [<options>] <name>. Furthermore some options can be permanently written into metadata of LUKS2 headers using cryptsetup's --persistent flag.
Note that the first three fields are required and that a missing field will lead to unspecified behaviour.
Please note that there are several independent cryptsetup wrappers with their own crypttab format. This manpage covers Debian's implementation for initramfs scripts and SysVinit init scripts. systemd brings its own crypttab implementation. We try to cover the differences between the systemd and our implementation in this manpage, but if in doubt, better check the systemd crypttab(5) manpage, e.g. online at https://www.freedesktop.org/software/systemd/man/crypttab.html.
cipher=<cipher>
size=<size>
sector-size=<bytes>
hash=<hash>
offset=<offset>
skip=<skip>
keyfile-offset=<keyfile-offset>
keyfile-size=<keyfile-size>
keyslot=<slot>, key-slot=<slot>
header=<path>
verify
readonly, read-only
tries=<num>
discard
Starting with Debian 10 (Buster), this option is added per default to new dm-crypt devices by the Debian Installer. If you don't care about leaking access patterns (filesystem type, used space) and don't have hidden truecrypt volumes inside this volume, then it should be safe to enable this option. See the following warning for further information.
WARNING: 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.
luks
plain
bitlk
fvault2
tcrypt
veracrypt, tcrypt-veracrypt
tcrypthidden, tcrypt-hidden
same-cpu-crypt
submit-from-crypt-cpus
no-read-workqueue, no-write-workqueue
swap
This option is ignored for initramfs devices.
tmp[=<tmpfs>]
This option is ignored for initramfs devices.
check[=<check>]
The program is either specified by full path or relative to /lib/cryptsetup/checks/. If omitted, then the value of $CRYPTDISKS_CHECK set in /etc/default/cryptdisks is used (blkid by default).
This option is specific to the Debian crypttab format. It's not supported by systemd.
checkargs=<arguments>
This option is specific to the Debian crypttab format. It's not supported by systemd.
initramfs
This option is specific to the Debian crypttab format. It's not supported by systemd.
noearly
This option is ignored for initramfs devices and specific to the Debian crypttab format. It's not supported by systemd.
noauto
This option is ignored for initramfs devices and specific to the Debian crypttab format. It's not supported by systemd.
loud
This option is ignored for initramfs devices and specific to the Debian crypttab format. It's not supported by systemd.
quiet
This option is ignored for initramfs devices and specific to the Debian crypttab format. It's not supported by systemd.
keyscript=<path>
LIMITATIONS: All binaries and files on which the keyscript depends must be available at the time of execution. Special care needs to be taken for encrypted filesystems like /usr or /var. As an example, unlocking encrypted /usr must not depend on binaries from /usr/(s)bin.
This option is specific to the Debian crypttab format. It's not supported by systemd.
WARNING: With systemd as init system, this option might be ignored. At the time this is written (December 2016), the systemd cryptsetup helper doesn't support the keyscript option to /etc/crypttab. For the time being, the only option to use keyscripts along with systemd is to force processing of the corresponding crypto devices in the initramfs. See the 'initramfs' option for further information.
All fields of the appropriate crypttab entry are available to the keyscript as exported environment variables:
CRYPTTAB_NAME, _CRYPTTAB_NAME
CRYPTTAB_SOURCE, _CRYPTTAB_SOURCE
CRYPTTAB_KEY, _CRYPTTAB_KEY
CRYPTTAB_OPTIONS, _CRYPTTAB_OPTIONS
CRYPTTAB_OPTION_<option>
CRYPTTAB_TRIED
blkid
un_blkid
# Encrypted swap device cswap /dev/sda6 /dev/urandom plain,cipher=aes-xts-plain64,size=256,hash=sha1,swap # Encrypted LUKS disk with interactive password, identified by its UUID, discard enabled cdisk0 UUID=12345678-9abc-def012345-6789abcdef01 none luks,discard # Encrypted TCRYPT disk with interactive password, discard enabled tdisk0 /dev/sr0 none tcrypt,discard # Encrypted ext4 disk with interactive password, discard enabled # - retry 5 times if the check fails cdisk1 /dev/sda2 none plain,cipher=aes-xts-plain64,size=256,hash=sha1,check,checkargs=ext4,tries=5,discard # Encrypted disk with interactive password, discard enabled # - use a nondefault check script # - no retries cdisk2 /dev/sdc1 none plain,cipher=aes-xts-plain64,size=256,hash=sha1,check=customscript,tries=1,discard # Encrypted disk with interactive password, discard enabled # - Twofish as the cipher, RIPEMD-160 as the hash cdisk3 /dev/sda3 none plain,cipher=twofish,size=256,hash=ripemd160,discard
CRYPTDISKS_ENABLE
CRYPTDISKS_MOUNT
CRYPTDISKS_CHECK
The upstream defaults for encryption cipher, hash and keysize have changed several times in the past, and they're expected to change again in future, for example if security issues arise. On LUKS devices, the used settings are stored in the LUKS header, and thus don't need to be configured in /etc/crypttab. For plain dm-crypt devices, no information about used cipher, hash and keysize are available at all. Therefore we strongly suggest to configure the cipher, hash and keysize in /etc/crypttab for plain dm-crypt devices, even if they match the current default.
cryptsetup(8), cryptdisks_start(8), cryptdisks_stop(8), /usr/share/doc/cryptsetup-initramfs/README.initramfs.gz
This manual page was originally written by Bastian Kleineidam <calvin@debian.org> for the Debian distribution of cryptsetup. It has been further improved by Michael Gebetsroither <michael.geb@gmx.at>, David Härdeman <david@hardeman.nu> and Jonas Meurer <jonas@freesources.org>.
2023-12-18 | cryptsetup 2:2.6.1-4~deb1 |