Skip to content

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 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).

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, hold your security key near the device (NFC).

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.

Limitations

  • systemd-fido2 token format only (as created by systemd-cryptenroll).
  • NFC only (USB/other transports are not implemented yet).
  • No PIN / user‑verification support yet. Tokens requiring PIN/UV 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.

Feedback

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