[email protected]8
Full disk decryption logic
Part of systemd-cryptsetup(8).
Usage
systemd-cryptsetup [OPTIONS ...]
attach
VOLUME
SOURCE-DEVICE
[KEY-FILE]
[CRYPTTAB-OPTIONS]
systemd-cryptsetup [OPTIONS ...]
detach
VOLUME
Overview
systemd-cryptsetup is used to set up (with attach) and tear down (with detach) access to an encrypted block device. It is primarily used via [email protected] during early boot, but may also be called manually. The positional arguments VOLUME, SOURCE-DEVICE, KEY-FILE, and CRYPTTAB-OPTIONS have the same meaning as the fields in crypttab(5).
[email protected] is a service responsible for providing access to encrypted block devices. It is instantiated for each device that requires decryption.
[email protected] instances are part of the system-systemd\x2dcryptsetup.slice slice, which is destroyed only very late in the shutdown procedure. This allows the encrypted devices to remain up until filesystems have been unmounted.
[email protected] will ask for hard disk passwords via the password agent logic[1], in order to query the user for the password using the right mechanism at boot and during runtime.
At early boot and when the system manager configuration is reloaded, /etc/crypttab is translated into [email protected] units by systemd-cryptsetup-generator(8).
In order to unlock a volume a password or binary key is required. [email protected] tries to acquire a suitable password or binary key via the following mechanisms, tried in order:
1. If a key file is explicitly configured (via the third column in /etc/crypttab), a key read from it is used. If a PKCS#11 token, FIDO2 token or TPM2 device is configured (using the pkcs11-uri=, fido2-device=, tpm2-device= options) the key is decrypted before use.
2. If no key file is configured explicitly this way, a key file is automatically loaded from /etc/cryptsetup-keys.d/volume.key and /run/cryptsetup-keys.d/volume.key, if present. Here too, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is decrypted before use.
3. If the try-empty-password option is specified then unlocking the volume with an empty password is attempted.
4. If the password-cache= option is set to "yes" or "read-only", the kernel keyring is then checked for a suitable cached password from previous attempts.
5. Finally, the user is queried for a password, possibly multiple times, unless the headless option is set.
If no suitable key may be acquired via any of the mechanisms describes above, volume activation fails.
Credentials
systemd-cryptsetup supports the service credentials logic as implemented by ImportCredential=/LoadCredential=/SetCredential= (see systemd.exec(5) for details). The following credentials are used by "[email protected]" (generated by systemd-gpt-auto-generator) when passed in:
cryptsetup.passphrase
This credential specifies the passphrase of the LUKS volume.
Added in version 256.
cryptsetup.tpm2-pin
This credential specifies the TPM pin.
Added in version 256.
cryptsetup.fido2-pin
This credential specifies the FIDO2 token pin.
Added in version 256.
cryptsetup.pkcs11-pin
This credential specifies the PKCS11 token pin.
Added in version 256.
cryptsetup.luks2-pin
This credential specifies the pin requested by generic LUKS2 token modules.
Added in version 256.
Notes
- 1.
-
password agent logic
https://systemd.io/PASSWORD_AGENTS/
- 2.
-
TPM2 PCR Measurements Made by systemd
https://systemd.io/TPM2_PCR_MEASUREMENTS
History
- Debian 13 (Trixie): the text shown here
- Debian 12 (Bookworm)
- Debian 11 (Bullseye)
- Debian 10 (Buster)
- Debian 9 (Stretch)
- Debian 8 (Jessie)