FIDO2 Security Keys¶

Disk Decipher can mount LUKS2 disk images that were enrolled with a FIDO2 security key using systemd-cryptenroll. The app reads the LUKS2 token metadata and uses NFC or USB to talk to the key, then derives the key material to unlock the correct keyslot.

This page explains:

• What the feature does
• How to create and enroll a compatible LUKS2 image on Linux
• How to use the option in Disk Decipher
• Current limitations (and how to give feedback)

Create a LUKS2 image on Linux¶

The steps below create a file-backed LUKS2 disk image, then format it with a filesystem. Adjust sizes and paths to your needs.

# Create a 1 GiB empty image file
truncate -s 1G /path/to/test.img

# Initialize as LUKS2 (this is destructive)
cryptsetup luksFormat --type luks2 /path/to/test.img

# Open it and create a filesystem (example: FAT)
cryptsetup luksOpen /path/to/test.img test
mkfs.vfat /dev/mapper/test
cryptsetup luksClose test

If you already have a LUKS2 device or image, you can skip the creation steps.

Enroll a FIDO2 security key (systemd)¶

Use systemd-cryptenroll to bind a FIDO2 token to the LUKS2 disk image:

# Enroll the first detected FIDO2 device (NFC/USB depending on your system)
systemd-cryptenroll --fido2-device=auto /path/to/test.img

Notes:

• If you enroll multiple tokens or change token parameters, the app may pick the first compatible token it finds (see limitations).
• Add the --wipe-slot=all option to systemd-cryptenroll if you want to disable opening the image with a password (token only).
• Add the --fido2-with-client-pin=no option to systemd-cryptenroll if you want to disable PIN-protection for the new token.
• If auto does not work for your setup or security key, use fido2-token -L first to get the device name of your security key. Then use /dev/... instead of auto in the enrollment command.

Mount in Disk Decipher¶

In Disk Decipher:

1. Open the LUKS2 image/drive as usual.
2. Optionally adjust the Security key usage advanced mount option:
   • Automatic — (Default) Use a token only for keyslots that are bound to a token.
   • Tokens only — Skip keyslots without a token.
   • Disabled — Skip keyslots that are bound to a token.
3. Continue mounting. When prompted, enter the PIN code and hold your security key near the device (NFC, for USB insert your security key).

Backup keys¶

It’s fine (and recommended) to enroll multiple FIDO2 keys. Each key will produce a distinct credential, typically stored in a separate LUKS2 keyslot. Disk Decipher’s initial release uses the first compatible token only, so additional enrolled keys won’t be used on mobile yet. Those backup keys continue to work on Linux, and the disk image is fully compatible there.

If you need a working mobile backup right now, consider keeping one keyslot protected by a strong password as a fallback. That preserves recovery if your primary key is unavailable.

Multi‑token selection on mobile is a good candidate for a future update—please let us know if this limitation affects your workflow.

Interfaces¶

The supported interfaces are summarized in this table

Limitations¶

• systemd-fido2 token format only (as created by systemd-cryptenroll).
• No user‑verification support yet. Tokens requiring UV (for instance, biometrics) are ignored.
• Single token path: the app uses the first compatible token it finds in the LUKS2 metadata.
• CTAP2 with hmac-secret only (no CTAP1/U2F).

If any of these limitations impact your workflow, please let us know so we can prioritize improvements.

Tested security keys¶

This feature has been tested with these FIDO2 security keys:

• YubiKey 5C NFC
• Feitian K40 Plus

Let us know if you use a different kind of brand/model so we can add it to this list. Both success and failure reports are welcome.

Feedback¶

We’d love to hear what you need next (token selection, UV, non‑systemd formats, etc.). Tell us your use case and we’ll evaluate priorities.