---

   crypttab    ( 5 )

---

KEY ACQUISITION

Six different mechanisms for acquiring the decryption key or passphrase unlocking the encrypted volume are supported. Specifically:

1. Most prominently, the user may be queried interactively during volume activation (i.e. typically at boot), asking them to type in the necessary passphrase(s).

2. The (unencrypted) key may be read from a file on disk, possibly on removable media. The third field of each line encodes the location, for details see above.

3. The (unencrypted) key may be requested from another service, by specifying an AF_UNIX file system socket in place of a key file in the third field. For details see above and below.

4. The key may be acquired via a PKCS#11 compatible hardware security token or smartcard. In this case an encrypted key is stored on disk/removable media, acquired via AF_UNIX, or stored in the LUKS2 JSON token metadata header. The encrypted key is then decrypted by the PKCS#11 token with an RSA key stored on it, and then used to unlock the encrypted volume. Use the pkcs11-uri= option described below to use this mechanism.

5. Similar, the key may be acquired via a FIDO2 compatible hardware security token (which must implement the "hmac-secret" extension). In this case a (during enrollment) randomly generated key is stored on disk/removable media, acquired via AF_UNIX, or stored in the LUKS2 JSON token metadata header. The random key is hashed via a keyed hash function (HMAC) on the FIDO2 token, using a secret key stored on the token that never leaves it. The resulting hash value is then used as key to unlock the encrypted volume. Use the fido2-device= option described below to use this mechanism.

6. Similar, the key may be acquired via a TPM2 security chip. In this case a (during enrollment) randomly generated key — encrypted by an asymmetric key derived from the TPM2 chip's seed key — is stored on disk/removable media, acquired via AF_UNIX, or stored in the LUKS2 JSON token metadata header. Use the tpm2-device= option described below to use this mechanism.

For the latter five mechanisms the source for the key material used for unlocking the volume is primarily configured in the third field of each /etc/crypttab line, but may also configured in /etc/cryptsetup-keys.d/ and /run/cryptsetup-keys.d/ (see above) or in the LUKS2 JSON token header (in case of the latter three). Use the systemd-cryptenroll(1) tool to enroll PKCS#11, FIDO2 and TPM2 devices in LUKS2 volumes.