How to use the command 'systemd-cryptenroll' (with examples)

The ‘systemd-cryptenroll’ command is used to interactively enroll or remove methods used to unlock LUKS2-encrypted devices. It can be used to enroll a new password, recovery key, PKCS#11 token, FIDO2 device, TPM2 security chip, or to remove any of these methods. This command is particularly useful for managing encryption for system boot and unlocking encrypted devices during system startup.

Use case 1: Enroll a new password

Code:

systemd-cryptenroll --password path/to/luks2_block_device

Motivation: Sometimes, it is necessary to enroll a new password to unlock a LUKS2-encrypted device, either for security purposes or to replace the existing password with a new one. This use case allows users to add a new password to the LUKS2 block device.

Explanation:

• --password: Specifies that a password will be used for unlocking the device.
• path/to/luks2_block_device: The path to the LUKS2 block device that needs a new password enrolled.

Example output:

Enter password for /dev/sdb1:
Please enter the new password for /dev/sdb1:
Password enrollment successful.

Use case 2: Enroll a new recovery key

Code:

systemd-cryptenroll --recovery-key path/to/luks2_block_device

Motivation: A recovery key is a randomly generated passphrase that serves as a fallback to unlock a LUKS2-encrypted device in case the primary unlocking method is unavailable or forgotten. This use case allows users to enroll a new recovery key for the LUKS2 block device.

Explanation:

• --recovery-key: Specifies that a recovery key passphrase will be used for fallback unlocking.
• path/to/luks2_block_device: The path to the LUKS2 block device that needs a new recovery key enrolled.

Example output:

Enter passphrase for /dev/sdb1:
Please enter the recovery key passphrase for /dev/sdb1:
Recovery key enrollment successful.

Use case 3: List available tokens, or enroll a new PKCS#11 token

Code:

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

Motivation: PKCS#11 is a cryptographic token interface standard that allows various cryptographic devices, such as smart cards or USB tokens, to be used for encryption. This use case allows users to list the available PKCS#11 tokens or enroll a new one for the LUKS2 block device.

Explanation:

• --pkcs11-token-uri: Specifies the PKCS#11 token URI. It can be one of the following:
  • list: Lists the available PKCS#11 tokens.
  • auto: Automatically selects a suitable PKCS#11 token.
  • pkcs11_token_uri: Specifies the URI of a specific PKCS#11 token.
• path/to/luks2_block_device: The path to the LUKS2 block device where the PKCS#11 token needs to be enrolled.

Example output:

Available PKCS#11 tokens:
1: SafeNet Luna CA3 (slot: 0)
2: YubiKey 5 NFC (slot: 1)

Enrolling PKCS#11 token successful.

Use case 4: List available FIDO2 devices, or enroll a new FIDO2 device

Code:

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

Motivation: FIDO2 is a set of standards for passwordless authentication using public-key cryptography. FIDO2 devices include physical devices like security keys or other authenticators. This use case allows users to list the available FIDO2 devices or enroll a new one for the LUKS2 block device.

Explanation:

• --fido2-device: Specifies the FIDO2 device. It can be one of the following:
  • list: Lists the available FIDO2 devices.
  • auto: Automatically selects a suitable FIDO2 device.
  • path/to/fido2_hidraw_device: Specifies the path to a specific FIDO2 device.
• path/to/luks2_block_device: The path to the LUKS2 block device where the FIDO2 device needs to be enrolled.

Example output:

Available FIDO2 devices:
1: YubiKey 5 NFC (hidraw0)
2: SoloKey (hidraw1)

Enrolling FIDO2 device successful.

Use case 5: Enroll a new FIDO2 device with user verification

Code:

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

Motivation: User verification adds an extra layer of security to FIDO2-based unlocking by requiring additional verification from the user, such as a biometric authentication. This use case allows users to enroll a new FIDO2 device with user verification for the LUKS2 block device.

Explanation:

• --fido2-device: Specifies the FIDO2 device. It can be one of the following:
  • auto: Automatically selects a suitable FIDO2 device.
  • path/to/fido2_hidraw_device: Specifies the path to a specific FIDO2 device.
• --fido2-with-user-verification: Specifies that user verification should be enabled for the FIDO2 device.
• path/to/luks2_block_device: The path to the LUKS2 block device where the FIDO2 device needs to be enrolled.

Example output:

Please touch the FIDO2 device for verification.
Enrolling FIDO2 device with user verification successful.

Use case 6: Unlock using a FIDO2 device, and enroll a new FIDO2 device

Code:

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

Motivation: This use case allows users to unlock a LUKS2-encrypted device using a specific FIDO2 device and simultaneously enroll another FIDO2 device for future unlock operations.

Explanation:

• --unlock-fido2-device: Specifies the FIDO2 device that will be used to unlock the LUKS2 block device.
• path/to/fido2_hidraw_unlock_device: The path to the specific FIDO2 device used for unlocking.
• --fido2-device: Specifies the FIDO2 device that will be enrolled for future unlock operations.
• path/to/fido2_hidraw_enroll_device: The path to the specific FIDO2 device to be enrolled.
• path/to/luks2_block_device: The path to the LUKS2 block device to be unlocked and enrolled.

Example output:

Unlocking LUKS2 block device using FIDO2 device /dev/hidraw0.
Please touch the FIDO2 device for verification.
Enrolling FIDO2 device successful.

Use case 7: Enroll a TPM2 security chip with PIN

Code:

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

Motivation: TPM2 is a security chip that provides hardware-based security features, such as storing encryption keys securely. This use case allows users to enroll a TPM2 security chip and require an additional alphanumeric PIN for unlocking the LUKS2 block device.

Explanation:

• --tpm2-device: Specifies the TPM2 device. It can be one of the following:
  • auto: Automatically selects a suitable TPM2 device.
  • path/to/tpm2_block_device: Specifies the path to a specific TPM2 device.
• --tpm2-with-pin: Specifies that an alphanumeric PIN should be required for unlocking the TPM2 device.
• path/to/luks2_block_device: The path to the LUKS2 block device where the TPM2 device needs to be enrolled.

Example output:

Enrolling TPM2 security chip with PIN successful.

Use case 8: Remove all empty passwords/all passwords/all FIDO2 devices/all PKCS#11 tokens/all TPM2 security chips/all recovery keys/all methods

Code:

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

Motivation: Sometimes, it is necessary to remove certain unlocking methods, such as empty passwords, passwords, FIDO2 devices, PKCS#11 tokens, TPM2 security chips, recovery keys, or all methods altogether. This use case allows users to wipe specific unlocking methods from the LUKS2 block device.

Explanation:

• --wipe-slot: Specifies the unlocking methods to be wiped. It can be one of the following:
  • empty: Removes empty passwords.
  • password: Removes passwords.
  • fido2: Removes FIDO2 devices.
  • pkcs#11: Removes PKCS#11 tokens.
  • tpm2: Removes TPM2 security chips.
  • recovery: Removes recovery keys.
  • all: Removes all unlocking methods.
• path/to/luks2_block_device: The path to the LUKS2 block device from which the unlocking methods need to be removed.

Example output:

Wipe successful. Removed all FIDO2 devices from /dev/sdb1.

Conclusion:

The ‘systemd-cryptenroll’ command is a versatile tool for managing encryption methods used to unlock LUKS2-encrypted devices. Whether it is enrolling new passwords, recovery keys, FIDO2 devices, PKCS#11 tokens, TPM2 security chips, or removing existing unlocking methods, this command provides a convenient and interactive way to manage device encryption. By using the ‘systemd-cryptenroll’ command, users can enhance the security of their encrypted devices and ensure smooth system boot and unlock operations.