systemd-cryptenroll

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:

To use PKCS#11 tokens, install libp11-kit.
To use FIDO2 tokens, install libfido2.
To use TPM2 devices, install tpm2-tss.

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.

After enrolling the hardware tokens into LUKS 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.

# systemd-cryptenroll /dev/disk --fido2-device=device

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

--fido2-with-client-pin defines whether to ask for a PIN before unlocking, defaults to no
--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

ノート:

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.

Trusted Platform Module

この記事またはセクションは加筆を必要としています。

理由: Document --tpm2-public-key (議論: トーク: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.

ノート: 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.