From ArchWiki

From systemd-cryptenroll(1):

systemd-cryptenroll is a tool for enrolling hardware security tokens and devices into a LUKS2 encrypted volume, which may then be used to unlock the volume during boot.

systemd-cryptenroll allows enrolling smartcards, FIDO2 tokens and Trusted Platform Module security chips into LUKS devices, as well as regular passphrases. These devices are later unlocked by systemd-cryptsetup@.service(8), using the enrolled tokens.

Installation

systemd-cryptenroll is part of and packaged with systemd. However, extra packages are required to use hardware devices as keys:

List keyslots

systemd-cryptenroll can list the keyslots in a LUKS device, similar to cryptsetup luksDump, but in a more user-friendly format.

# systemd-cryptenroll /dev/disk
SLOT TYPE    
   0 password
   1 tpm2

Erasing keyslots

# systemd-cryptenroll /dev/disk --wipe-slot=SLOT

Where SLOT can be:

  • A single keyslot index, as represented in #List keyslots
  • A type of keyslot, which will erase all keyslots of that type. Valid types are empty, password, recovery, pkcs11, fido2, tpm2
  • A combination of all of the above, separated by commas
  • The string all, which erases all keyslots on the device. This option can only be used when enrolling another device or passphrase at the same time.

The --wipe-slot operation can be used in combination with all enrollment options, which is useful to update existing device enrollments:

# systemd-cryptenroll /dev/disk --wipe-slot=fido2 --fido2-device=auto

Enrolling passphrases

Regular password

This is equivalent to cryptsetup luksAddKey.

# systemd-cryptenroll /dev/disk --password

Recovery key

From systemd-cryptenroll(1):

Recovery keys are mostly identical to passphrases, but are computer-generated instead of being chosen by a human, and thus have a guaranteed high entropy. The key uses a character set that is easy to type in, and may be scanned off screen via a QR code.

A recovery key is designed to be used as a fallback if the hardware tokens are unavailable, and can be used in place of regular passphrases whenever they are required.

# systemd-cryptenroll /dev/disk --recovery-key

Enrolling hardware devices

The --type-device options must point to a valid device path of their respective type. A list of available devices can be obtained by passing the list argument to this option. Alternatively, if you only have a single device of the desired type connected, the auto option can be used to automatically select it.

Note: After enrolling the hardware tokens into the LUKS2 volumes, you must configure your system to use them when appropriate. See dm-crypt/System configuration#Trusted Platform Module and FIDO2 keys for volumes that should be unlocked in early userspace like the root filesystem, and dm-crypt/System configuration#Unlocking in late userspace for other partitions.

PKCS#11 tokens or smartcards

The token or smartcard must contain a RSA key pair, which will be used to encrypt the generated key that will be used to unlock the volume.

# systemd-cryptenroll /dev/disk --pkcs11-token-uri=device

FIDO2 tokens

Any FIDO2 token that supports the "hmac-secret" extension can be used with systemd-cryptenroll. The following example would enroll a FIDO2 token to an encrypted LUKS2 block device, requiring only user presence as authentication.

# systemd-cryptenroll /dev/disk --fido2-device=device --fido2-with-client-pin=no

In addition, systemd-cryptenroll supports using the token's built-in user verification methods:

  • --fido2-with-user-presence defines whether to verify the user presence (i.e. by tapping the token) before unlocking, defaults to yes
  • --fido2-with-user-verification defines whether to require user verification before unlocking, defaults to no
Note:
  • These options will have no effect if the token does not support these features.
  • See User Presence vs User Verification for more information on the difference between the two.

Furthermore, if desired and provided by the FIDO2 token, a different cryptographic algorithm can be specified during enrollment. Suppose that a previous FIDO2 token has already been enrolled and the user wishes to enroll another, the following generates an eddsa credential which denotes EDDSA over Curve25519 with SHA-512 and authenticates the device with a previous enrolled token instead of a password.

# systemd-cryptenroll /dev/disk --fido2-device=device --fido2-credential-algorithm=eddsa --unlock-fido2-device=auto
Note: Both tokens must be plugged in to the system for successful enrollment.

Trusted Platform Module

This article or section needs expansion.

Reason: Document --tpm2-public-key (Discuss in Talk:Systemd-cryptenroll)
# systemd-cryptenroll /dev/disk --tpm2-device=device

By default, enrolling a TPM will bind the key to PCR7, which measures the Secure Boot state. It is possible to change which PCRs the key will be bound to by using the --tpm2-pcrs option. Multiple PCRs can be used at once by separating them with + symbol. A full list of PCRs and what they measure is available in Trusted Platform Module#Accessing PCR registers.

Using TPM with a PIN

It is possible to require a PIN to be entered in addition to the TPM measurement check. Add the option --tpm2-with-pin=yes while enrolling a TPM device, then enter the PIN when asked. Although systemd-cryptenroll calls this a PIN, any characters may be used.

Note: systemd-cryptenroll does not check the TPM measurement before asking for the PIN, therefore consider using a unique PIN since the environment may be untrustworthy.

See also