How to Unlock a LUKS Disk with a Security Key
Full-Disk Encryption, Unlocked by Hardware
Desktop
systemd-cryptenroll can add a FIDO2 device as an unlock method on a LUKS2 volume, alongside your existing passphrase. It works through the hmac-secret extension, which Seedkeeper PRO supports.
Enrolling and unlocking on a running system works well. Unlocking the root disk at boot is a different matter with an NFC-only device, and this page is honest about why.
Overview
LUKS stores your disk's master key in a header, encrypted several times over in separate keyslots. A passphrase unlocks one slot; a FIDO2 device can unlock another. Adding one does not remove the other, which is the property this whole guide leans on.
The device does not store the disk key. It derives a secret using the hmac-secret extension - the same mechanism behind WebAuthn PRF - and that secret unlocks the slot. Present the same device and you get the same secret; present anything else and you get nothing useful. See Device Capabilities.
The default your browser offers - Face ID, Touch ID, Windows Hello, or a synced credential manager - creates a perfectly valid passkey.
Choosing your Seedkeeper PRO instead changes three things:
- The key exists in one place only. A synced passkey is copied across every device on your cloud account, and that account is usually protected by a password. A hardware passkey is generated inside a certified secure element and physically cannot leave it.
- Nobody else is in the chain. No provider account, no cloud, no vendor login standing between you and your own credentials.
- It travels. The same card or ring works on your phone, your laptop, and a machine that isn't yours - a work computer, a shared workstation - leaving nothing behind.
See "Not All Passkeys Are Stored the Same Way" for the full comparison.
The NFC Problem, Stated Up Front
Most guides on this subject assume a USB security key, and quietly skip what follows.
A USB FIDO2 key speaks HID. The kernel handles it, libfido2 talks to it directly, and it works inside an initramfs with nothing extra installed.
Seedkeeper PRO has no USB interface. It speaks NFC and ISO 7816 contact, which on Linux means the PC/SC stack: the pcscd daemon, the CCID driver, and your reader's support. On a running system that is a package install. Inside an initramfs it is not, because no distribution includes any of it by default.
This splits the article into two very different cases:
| Scenario | Works? |
|---|---|
| Secondary volume unlocked on a running system | ✅ Reliably |
| Home directory or external drive, unlocked after login | ✅ Reliably |
| Root disk at boot | ⚠️ Requires a custom initramfs, covered at the end |
If you want disk encryption unlocked by hardware today, without building an initramfs, encrypt a secondary volume rather than the root disk. That is a genuinely useful setup and the rest of this guide gets you there.
Before You Start
# Debian, Ubuntu
sudo apt install pcscd pcsc-tools libfido2-1 fido2-tools cryptsetup
# RHEL, Fedora, Rocky
sudo dnf install pcsc-lite pcsc-tools libfido2 fido2-tools cryptsetup
sudo systemctl enable --now pcscd
fido2-token -L
fido2-token -L must list your device. If it does not, nothing below will work - see Connection and NFC Issues.
Check your systemd version and your LUKS format:
systemctl --version | head -1 # need 248 or later
sudo cryptsetup luksDump /dev/sdXn | head -5
The dump must say LUKS2. LUKS1 has no token support and cannot do this; converting is possible but out of scope here and not risk-free.
Every operation below writes to the LUKS header. A damaged header means an unrecoverable disk, however good your passphrase is.
sudo cryptsetup luksHeaderBackup /dev/sdXn \
--header-backup-file ~/luks-header-backup.img
Copy that file somewhere off the machine. It is as sensitive as the disk itself.
Step 1: Enroll the Device
sudo systemd-cryptenroll /dev/sdXn \
--fido2-device=auto \
--fido2-with-client-pin=yes
You will be asked for an existing passphrase first - that is how the tool gets the master key to write a new slot - then to present the device and enter its PIN.
Options worth knowing:
--fido2-with-client-pin=yesrequires the FIDO PIN at every unlock. This is the default and worth keeping: without it, possession of the card alone opens the disk.--fido2-with-user-presence=yesrequires a physical tap.--fido2-device=autopicks the only device present. With several attached, list them withsystemd-cryptenroll --fido2-device=listand name one explicitly.
Confirm the new slot exists:
sudo cryptsetup luksDump /dev/sdXn | grep -A3 Tokens
A systemd-fido2 token should be listed.
Step 2: Test Before You Depend on It
Do this on a volume you can afford to leave locked.
sudo cryptsetup luksClose myvolume # if currently open
sudo systemd-cryptsetup attach myvolume /dev/sdXn - fido2-device=auto
You should be prompted for the PIN and asked to present the device. If it opens, the enrolment is sound.
If it fails, your passphrase still works - that is why it is still enrolled.
Step 3: Unlock Automatically at Mount Time
For a secondary volume, add it to /etc/crypttab:
myvolume UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx none fido2-device=auto,nofail
Find the UUID with sudo blkid /dev/sdXn.
nofail matters more than it looks: without it, a boot where the device is absent or the reader is not ready stops at an emergency shell. With it, the volume is simply skipped and you mount it manually later.
Reload and test:
sudo systemctl daemon-reload
sudo systemctl restart systemd-cryptsetup@myvolume.service
The Root Disk at Boot
Here is where the NFC constraint becomes real.
At boot, the initramfs must unlock the root disk before any normal filesystem exists. For a USB key that is fine, because libfido2 talks to HID devices directly. For an NFC or contact device, the initramfs would need pcscd, the CCID driver, your reader's firmware if it needs one, and the USB stack to reach the reader - none of which any distribution ships in its initramfs.
This is not a Seedkeeper limitation. Any smartcard-based FIDO2 authenticator faces exactly the same wall.
Three honest options:
Encrypt a secondary volume instead. Root stays on a passphrase, and your actual data sits on a volume unlocked by hardware. This covers most of what people want and needs no initramfs work at all.
Build a custom initramfs. Possible with dracut, by writing a module that pulls in pcscd, libccid and the reader's dependencies, then starts the daemon early. This is real engineering work, it breaks on kernel and distribution updates, and a mistake leaves an unbootable machine. Worth it only if you know exactly why you need it.
Use a USB FIDO2 key for the root disk, and your Seedkeeper PRO for everything else - SSH, login, secondary volumes. Unsatisfying, and the pragmatic answer for a laptop that must boot reliably.
Whichever you choose, keep the passphrase slot. It is the only thing standing between a failed unlock and a lost disk.
Removing a Device
Lost the card, or retiring one:
# see which slot the token occupies
sudo cryptsetup luksDump /dev/sdXn
# remove it
sudo systemd-cryptenroll /dev/sdXn --wipe-slot=fido2
--wipe-slot=fido2 removes every FIDO2 slot on that volume. With two devices enrolled and only one lost, remove all of them and re-enroll the one you still hold.
Never wipe the passphrase slot unless another method is confirmed working on that exact machine, at boot, more than once.
FAQ
Can I unlock a LUKS disk with a FIDO2 security key?
Yes. systemd-cryptenroll adds a FIDO2 device as an unlock method on a LUKS2 volume, alongside your existing passphrase. It requires systemd 248 or later and LUKS2, not LUKS1.
Does this replace my LUKS passphrase?
No, and you should not let it. The key is added as an additional keyslot. Keeping the passphrase is what saves you when the device is lost, damaged, or simply not detected at boot.
Does this work with an NFC-only device at boot?
Enrolling and unlocking on a running system works. Unlocking at boot is harder, because the initramfs needs pcscd and the reader drivers, which no distribution includes by default. See The Root Disk at Boot above.
Which systemd version do I need?
248 or later for FIDO2 support in systemd-cryptenroll. Debian 12, Ubuntu 22.04 and RHEL 9 all ship something newer.
Is my disk encryption key stored on the security key?
No. The device derives a secret through the hmac-secret extension, and that secret unlocks the keyslot. The disk key never leaves the LUKS header, and the device holds nothing that identifies the disk.
What happens if I lose the security key?
You unlock with your passphrase, then remove the orphaned keyslot with systemd-cryptenroll --wipe-slot=fido2. This is the entire reason to keep the passphrase enrolled.