From 2cb7e0aaedad73b076ea18c6900b0e86c5760d79 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 15:00:47 +0200 Subject: Adding upstream version 247.3. Signed-off-by: Daniel Baumann --- man/crypttab.xml | 575 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 575 insertions(+) create mode 100644 man/crypttab.xml (limited to 'man/crypttab.xml') diff --git a/man/crypttab.xml b/man/crypttab.xml new file mode 100644 index 0000000..0519242 --- /dev/null +++ b/man/crypttab.xml @@ -0,0 +1,575 @@ + + + + + + + + crypttab + systemd + + + + crypttab + 5 + + + + crypttab + Configuration for encrypted block devices + + + + /etc/crypttab + + + + Description + + The /etc/crypttab file describes + encrypted block devices that are set up during system boot. + + Empty lines and lines starting with the # + character are ignored. Each of the remaining lines describes one + encrypted block device. Fields are delimited by white space. + + Each line is in the formvolume-name encrypted-device key-file options + The first two fields are mandatory, the remaining two are + optional. + + Setting up encrypted block devices using this file supports + three encryption modes: LUKS, TrueCrypt and plain. See + cryptsetup8 + for more information about each mode. When no mode is specified in + the options field and the block device contains a LUKS signature, + it is opened as a LUKS device; otherwise, it is assumed to be in + raw dm-crypt (plain mode) format. + + The first field contains the name of the resulting encrypted volume; its block device is set up + below /dev/mapper/. + + The second field contains a path to the underlying block + device or file, or a specification of a block device via + UUID= followed by the UUID. + + The third field specifies an absolute path to a file with the encryption key. Optionally, + the path may be followed by : and an fstab device specification (e.g. starting with + LABEL= or similar); in which case the path is taken relative to the device file system + root. If the field is not present or is none or -, a key file + named after the volume to unlock (i.e. the first column of the line), suffixed with + .key is automatically loaded from the /etc/cryptsetup-keys.d/ + and /run/cryptsetup-keys.d/ directories, if present. Otherwise, the password has to + be manually entered during system boot. For swap encryption, /dev/urandom may be + used as key file. + + The fourth field, if present, is a comma-delimited list of + options. The following options are recognized: + + + + + + + Specifies the cipher to use. See cryptsetup8 + for possible values and the default value of this option. A cipher with unpredictable IV values, such + as aes-cbc-essiv:sha256, is recommended. Embedded commas in the cipher + specification need to be escaped by preceding them with a backslash, see example below. + + + + + + + Allow discard requests to be passed through the encrypted block + device. This improves performance on SSD storage but has security implications. + + + + + + + Specifies the hash to use for password + hashing. See + cryptsetup8 + for possible values and the default value of this + option. + + + + + + Use a detached (separated) metadata device or + file where the LUKS header is stored. This option is only + relevant for LUKS devices. See + cryptsetup8 + for possible values and the default value of this + option. + + Optionally, the path may be followed by : and an fstab device specification + (e.g. starting with UUID= or similar); in which case, the path is relative to the + device file system root. The device gets mounted automatically for LUKS device activation duration only. + + + + + + + Specifies the number of bytes to skip at the + start of the key file. See + cryptsetup8 + for possible values and the default value of this + option. + + + + + + Specifies the maximum number of bytes to read + from the key file. See + cryptsetup8 + for possible values and the default value of this option. This + option is ignored in plain encryption mode, as the key file + size is then given by the key size. + + + + + + If enabled, the specified key file is erased after the volume is activated or when + activation fails. This is in particular useful when the key file is only acquired transiently before + activation (e.g. via a file in /run/, generated by a service running before + activation), and shall be removed after use. Defaults to off. + + + + + + Specifies the key slot to compare the + passphrase or key against. If the key slot does not match the + given passphrase or key, but another would, the setup of the + device will fail regardless. This option implies + . See + cryptsetup8 + for possible values. The default is to try all key slots in + sequential order. + + + + + + Specifies the timeout for the device on + which the key file resides and falls back to a password if + it could not be mounted. See + systemd-cryptsetup-generator8 + for key files on external devices. + + + + + + + Force LUKS mode. When this mode is used, the + following options are ignored since they are provided by the + LUKS header on the device: , + , + . + + + + + + Decrypt Bitlocker drive. Encryption parameters + are deduced by cryptsetup from Bitlocker header. + + + + + + Marks this cryptsetup device as requiring network. It will be + started after the network is available, similarly to + systemd.mount5 + units marked with . The service unit to set up this device + will be ordered between remote-fs-pre.target and + remote-cryptsetup.target, instead of + cryptsetup-pre.target and + cryptsetup.target. + + Hint: if this device is used for a mount point that is specified in + fstab5, + the option should also be used for the mount + point. Otherwise, a dependency loop might be created where the mount point + will be pulled in by local-fs.target, while the + service to configure the network is usually only started after + the local file system has been mounted. + + + + + + + This device will not be added to cryptsetup.target. + This means that it will not be automatically unlocked on boot, unless something else pulls + it in. In particular, if the device is used for a mount point, it'll be unlocked + automatically during boot, unless the mount point itself is also disabled with + . + + + + + + This device will not be a hard dependency of + cryptsetup.target. It'll still be pulled in and started, but the system + will not wait for the device to show up and be unlocked, and boot will not fail if this is + unsuccessful. Note that other units that depend on the unlocked device may still fail. In + particular, if the device is used for a mount point, the mount point itself also needs to + have the option, or the boot will fail if the device is not unlocked + successfully. + + + + + + Start offset in the backend device, in 512-byte sectors. This + option is only relevant for plain devices. + + + + + + Force plain encryption mode. + + + + + + Set up the encrypted block device in read-only + mode. + + + + + + Perform encryption using the same cpu that IO was submitted on. The default is to use + an unbound workqueue so that encryption work is automatically balanced between available CPUs. + + This requires kernel 4.0 or newer. + + + + + + + Disable offloading writes to a separate thread after encryption. There are some + situations where offloading write requests from the encryption threads to a dedicated thread degrades + performance significantly. The default is to offload write requests to a dedicated thread because it + benefits the CFQ scheduler to have writes submitted using the same context. + + This requires kernel 4.0 or newer. + + + + + + + Bypass dm-crypt internal workqueue and process read requests synchronously. The + default is to queue these requests and process them asynchronously. + + This requires kernel 5.9 or newer. + + + + + + Bypass dm-crypt internal workqueue and process write requests synchronously. The + default is to queue these requests and process them asynchronously. + + This requires kernel 5.9 or newer. + + + + + + + How many 512-byte sectors of the encrypted data to skip at the + beginning. This is different from the option with respect + to the sector numbers used in initialization vector (IV) calculation. Using + will shift the IV calculation by the same negative + amount. Hence, if is given, + sector n will get a sector number of 0 for the IV + calculation. Using causes sector + n to also be the first sector of the mapped device, but + with its number for IV generation being n. + + This option is only relevant for plain devices. + + + + + + + Specifies the key size in bits. See + cryptsetup8 + for possible values and the default value of this + option. + + + + + + Specifies the sector size in bytes. See + cryptsetup8 + for possible values and the default value of this + option. + + + + + + The encrypted block device will be used as a + swap device, and will be formatted accordingly after setting + up the encrypted block device, with + mkswap8. + This option implies . + + WARNING: Using the option will + destroy the contents of the named partition during every boot, + so make sure the underlying block device is specified + correctly. + + + + + + Use TrueCrypt encryption mode. When this mode + is used, the following options are ignored since they are + provided by the TrueCrypt header on the device or do not + apply: + , + , + , + , + . + + When this mode is used, the passphrase is read from the + key file given in the third field. Only the first line of this + file is read, excluding the new line character. + + Note that the TrueCrypt format uses both passphrase and + key files to derive a password for the volume. Therefore, the + passphrase and all key files need to be provided. Use + to provide the absolute path + to all key files. When using an empty passphrase in + combination with one or more key files, use + /dev/null as the password file in the third + field. + + + + + + Use the hidden TrueCrypt volume. This option + implies . + + This will map the hidden volume that is inside of the + volume provided in the second field. Please note that there is + no protection for the hidden volume if the outer volume is + mounted instead. See + cryptsetup8 + for more information on this limitation. + + + + + + Specifies the absolute path to a key file to + use for a TrueCrypt volume. This implies + and can be used more than once to + provide several key files. + + See the entry for on the + behavior of the passphrase and key files when using TrueCrypt + encryption mode. + + + + + + Use TrueCrypt in system encryption mode. This + option implies . + + + + + + Check for a VeraCrypt volume. VeraCrypt is a fork of + TrueCrypt that is mostly compatible, but uses different, stronger key + derivation algorithms that cannot be detected without this flag. + Enabling this option could substantially slow down unlocking, because + VeraCrypt's key derivation takes much longer than TrueCrypt's. This + option implies . + + + + + + Specifies the timeout for querying for a + password. If no unit is specified, seconds is used. Supported + units are s, ms, us, min, h, d. A timeout of 0 waits + indefinitely (which is the default). + + + + + + The encrypted block device will be prepared for using it as + /tmp/; it will be formatted using mkfs8. Takes + a file system type as argument, such as ext4, xfs or + btrfs. If no argument is specified defaults to ext4. This + option implies . + + WARNING: Using the option will destroy the contents of the named partition + during every boot, so make sure the underlying block device is specified correctly. + + + + + + Specifies the maximum number of times the user + is queried for a password. The default is 3. If set to 0, the + user is queried for a password indefinitely. + + + + + + If the encryption password is read from console, it has to be entered twice to + prevent typos. + + + + + + Takes a RFC7512 PKCS#11 URI + pointing to a private RSA key which is used to decrypt the key specified in the third column of the + line. This is useful for unlocking encrypted volumes through security tokens or smartcards. See below + for an example how to set up this mechanism for unlocking a LUKS volume with a YubiKey security + token. The specified URI can refer directly to a private RSA key stored on a token or alternatively + just to a slot or token, in which case a search for a suitable private RSA key will be performed. In + this case if multiple suitable objects are found the token is refused. The key configured in the + third column is passed as is to RSA decryption. The resulting decrypted key is then base64 encoded + before it is used to unlock the LUKS volume. + + + + + + Takes a boolean argument. If enabled, right before asking the user for a password it + is first attempted to unlock the volume with an empty password. This is useful for systems that are + initialized with an encrypted volume with only an empty password set, which shall be replaced with a + suitable password during first boot, but after activation. + + + + + + Specifies how long systemd should wait for a device to show up + before giving up on the entry. The argument is a time in seconds or explicitly + specified units of + s, + min, + h, + ms. + + + + + + + Setup this encrypted block device in the initramfs, similarly to + systemd.mount5 + units marked with . + + Although it's not necessary to mark the mount entry for the root file system with + , is still recommended with + the encrypted block device containing the root file system as otherwise systemd will + attempt to detach the device during the regular system shutdown while it's still in + use. With this option the device will still be detached but later after the root file + system is unmounted. + + All other encrypted block devices that contain file systems mounted in the initramfs + should use this option. + + + + + + At early boot and when the system manager configuration is + reloaded, this file is translated into native systemd units by + systemd-cryptsetup-generator8. + + + + Examples + + /etc/crypttab example + Set up four encrypted block devices. One using LUKS for normal storage, another one for usage as + a swap device and two TrueCrypt volumes. For the fourth device, the option string is interpreted as two + options cipher=xchacha12,aes-adiantum-plain64, + keyfile-timeout=10s. + + luks UUID=2505567a-9e27-4efe-a4d5-15ad146c258b +swap /dev/sda7 /dev/urandom swap +truecrypt /dev/sda2 /etc/container_password tcrypt +hidden /mnt/tc_hidden /dev/null tcrypt-hidden,tcrypt-keyfile=/etc/keyfile +external /dev/sda3 keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchacha12\,aes-adiantum-plain64 + + + + + Yubikey-based Volume Unlocking Example + + The PKCS#11 logic allows hooking up any compatible security token that is capable of storing RSA + decryption keys. Here's an example how to set up a Yubikey security token for this purpose, using + ykmap1 + from the yubikey-manager project: + + + +A few notes on the above: + + + We use RSA (and not ECC), since Yubikeys support PKCS#11 Decrypt() only for RSA keys + We use RSA2048, which is the longest key size current Yubikeys support + LUKS key size must be shorter than 2048bit due to RSA padding, hence we use 128 bytes + We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes, + see + documentation. + + + + + + + See Also + + systemd1, + systemd-cryptsetup@.service8, + systemd-cryptsetup-generator8, + fstab5, + cryptsetup8, + mkswap8, + mke2fs8 + + + + -- cgit v1.2.3