systemd-cryptenroll

Enroll a new password (similar to cryptsetup luksAddKey)

$ systemd-cryptenroll --password [path/to/luks2_block_device]

$ systemd-cryptenroll --recovery-key [path/to/luks2_block_device]

$ systemd-cryptenroll --pkcs11-token-uri [list|auto|pkcs11_token_uri] [path/to/luks2_block_device]

$ systemd-cryptenroll --fido2-device [list|auto|path/to/fido2_hidraw_device] [path/to/luks2_block_device]

$ systemd-cryptenroll --fido2-device [auto|path/to/fido2_hidraw_device] --fido2-with-user-verification yes [path/to/luks2_block_device]

$ systemd-cryptenroll --unlock-fido2-device [path/to/fido2_hidraw_unlock_device] --fido2-device [path/to/fido2_hidraw_enroll_device] [path/to/luks2_block_device]

$ systemd-cryptenroll --tpm2-device [auto|path/to/tpm2_block_device] --tpm2-with-pin yes [path/to/luks2_block_device]

$ systemd-cryptenroll --wipe-slot [empty|password|fido2|pkcs#11|tpm2|recovery|all] [path/to/luks2_block_device]

systemd-cryptenroll [OPTIONS...] [DEVICE|UUID=...] [SLOT]

--fido2-device=PATH
    Specify the FIDO2 device path (e.g., auto or /dev/hidrawX).

--fido2-with-client-pin=BOOL
    Require a client PIN for FIDO2 authentication.

--fido2-with-user-verification=BOOL
    Require user verification (e.g., fingerprint, PIN) for FIDO2.

--fido2-with-hmac-secret=BOOL
    Use HMAC-Secret extension for FIDO2 (recommended for disk encryption).

--fido2-with-user-presence=BOOL
    Require user presence (e.g., touch) for FIDO2.

--tpm2-device=PATH
    Specify the TPM2 device path (e.g., auto or /dev/tpmrm0).

--tpm2-pcrs=PCRS
    List of PCRs (Platform Configuration Registers) to seal to (e.g., 0+2+7).

--tpm2-set-pkcs11-token=BOOL
    Create a PKCS#11 token for the TPM2-protected key slot.

--recovery-key
    Generate and enroll a new recovery key.

--wipe-slot=SLOT
    Wipe a specific key slot by its number.

--wipe-fido2
    Wipe all FIDO2 credentials from the LUKS volume.

--wipe-tpm2
    Wipe all TPM2 credentials from the LUKS volume.

--wipe-recovery-key
    Wipe all recovery keys from the LUKS volume.

--wipe-all
    Wipe all credentials (all FIDO2, TPM2, recovery keys, and optionally passwords).

--unlock-key-slot=SLOT
    Specify a key slot to unlock the LUKS volume for enrollment (e.g., for password-based keys).

--password
    Use a password for enrollment (prompts for it).

--dry-run
    Perform a trial run without making any actual changes.

-h, --help
    Display a help message and exit.

--version
    Show version information and exit.

--no-pager
    Do not pipe output into a pager.

--no-legend
    Do not print the column legend.

--json=MODE
    Output data in JSON format for scripting.

systemd-cryptenroll is a command-line utility designed to manage security credentials for LUKS2 encrypted volumes, particularly integrating with the systemd ecosystem. Its primary function is to enroll or remove advanced unlock methods such as FIDO2 security tokens, TPM2 (Trusted Platform Module) devices, and recovery keys. This allows for unlocking encrypted disks at boot time, either manually or automatically (e.g., using TPM2 sealing with specific PCRs linked to Secure Boot policies).

While it can technically add password-based keys, `cryptsetup luksAddKey` is generally preferred for that purpose. systemd-cryptenroll excels in scenarios requiring hardware-backed authentication or dedicated recovery mechanisms, simplifying the management of these complex unlock methods within a systemd-managed environment. It supports both adding new credentials and selectively wiping existing ones from LUKS key slots.

systemd-cryptenroll specifically supports LUKS2 volumes; it will not work with LUKS1. It relies on the presence of underlying libraries like libfido2 and tpm2-tools for its advanced functionalities. While it can manage password-based keys, `cryptsetup luksAddKey` is generally the more direct and traditional tool for that purpose. Ensure the specified FIDO2 or TPM2 device is accessible and correctly configured.

Using TPM2 with PCRs provides strong binding to the system's boot state, preventing unauthorized decryption if the system configuration changes. FIDO2 tokens offer robust multi-factor authentication. Always store recovery keys securely in an offline location.

The DEVICE argument can be a path to a block device (e.g., /dev/sda1) or a UUID (e.g., UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

LUKS volumes have multiple key slots. `systemd-cryptenroll` can use an existing key (e.g., a password) to unlock the volume and then add a new credential into an available slot, or wipe specific slots.

systemd-cryptenroll emerged as part of the broader systemd initiative to streamline and integrate system-level functionalities, including disk encryption. Its development reflects a move towards more robust and automated boot processes, particularly for systems utilizing hardware security modules like TPMs and FIDO2 devices. It provides a more modern and systemd-aware approach to managing LUKS key material compared to the traditional `cryptsetup` commands, focusing on advanced cryptographic token integration.

cryptsetup(8), systemd-cryptsetup@.service(8), fido2-device(7), tpm2-tools(8)