LUKS Disk Encryption with Yubikey

Full disk encryption protects your data at rest. A strong LUKS passphrase is a reasonable first line of defence, but a passphrase alone has limitations: it can be observed, guessed, or extracted from a compromised system. Adding a Yubikey to the unlock process means the disk requires both something you know (the passphrase or PIN) and something you have (the physical key). Without the Yubikey present at boot, the drive will not open regardless of what passphrase is entered.

This page covers the modern approach using systemd-cryptenroll with FIDO2, which is the correct method on Kubuntu 24.04. The older yubikey-luks package referenced in the source material this series draws from is no longer the right tool for this.

Prerequisites

Before starting, confirm a few things are in place:

Your disk must be using LUKS2, not the older LUKS1 format. LUKS2 is the default on fresh Kubuntu 24.04 installations. Check which version your encrypted partition uses:

sudo cryptsetup luksDump /dev/nvme0n1p3 | grep "Version"

If the output shows Version: 1, the approach on this page will not work directly. LUKS1 volumes can be converted to LUKS2 but that is outside the scope of this page.

Your Yubikey 5 must have FIDO2 support enabled. All Yubikey 5 series devices support FIDO2 by default. Verify with:

ykman info

The output should list FIDO2 as an enabled application.

Identify your encrypted partition. On a typical NVMe installation this is something like /dev/nvme0n1p3. Find it with:

lsblk -f

Look for the partition with crypto_LUKS in the FSTYPE column. Set it as a variable for use in the commands below:

export LUKS_DEVICE=/dev/nvme0n1p3

Install required packages

sudo apt install libfido2-1 fido2-tools

The fido2-tools package provides the fido2-token command for verifying FIDO2 device status. libfido2-1 is the library that systemd-cryptenroll uses to communicate with the key.

Generate a recovery key first

Before enrolling the Yubikey, generate a recovery key. This is a randomly generated high-entropy passphrase that can unlock the volume if the Yubikey is lost or damaged. Without a recovery key, a lost Yubikey means a locked drive.

sudo systemd-cryptenroll --recovery-key $LUKS_DEVICE

The command will display a recovery key and a QR code. Write the recovery key down on paper and store it somewhere physically secure and separate from the machine. This is not the place to cut corners.

Verify the recovery key is enrolled:

sudo cryptsetup luksDump $LUKS_DEVICE | grep -A2 "Tokens"

Enroll the Yubikey via FIDO2

With the recovery key safely stored, enroll the Yubikey:

sudo systemd-cryptenroll --fido2-device=auto $LUKS_DEVICE

The command will prompt you to touch the Yubikey. Touch it when the light flashes. You may also be prompted to set a FIDO2 PIN if the key does not already have one configured.

By default this enrolls the key without requiring a PIN at boot. To require a PIN entry in addition to physical touch, add --fido2-with-client-pin=yes:

sudo systemd-cryptenroll --fido2-device=auto \
    --fido2-with-client-pin=yes $LUKS_DEVICE

The PIN-required option is the more secure choice. It means an attacker who steals both your laptop and your Yubikey still cannot unlock the disk without the PIN. The trade-off is one more thing to enter at boot.

Verify the enrolment:

sudo cryptsetup luksDump $LUKS_DEVICE

The Tokens section should now show a systemd-fido2 entry alongside any recovery key token.

Configure crypttab

Tell the system to use FIDO2 for unlocking at boot by updating /etc/crypttab. Find the existing entry for your encrypted partition:

cat /etc/crypttab

The line will look something like:

nvme0n1p3_crypt UUID=your-uuid-here none luks,discard

Add fido2-device=auto to the options:

nvme0n1p3_crypt UUID=your-uuid-here none luks,discard,fido2-device=auto

If you enrolled with PIN required, also add fido2-with-client-pin=true:

nvme0n1p3_crypt UUID=your-uuid-here none luks,discard,fido2-device=auto,fido2-with-client-pin=true

Update initramfs

The initramfs needs to include the FIDO2 libraries so they are available before the root filesystem is mounted. Update it:

sudo update-initramfs -u -k all

A note on Kubuntu 24.04 and initramfs

There is a known complication with FIDO2 LUKS unlock on Kubuntu 24.04 that is worth being upfront about. The standard initramfs-tools approach does not always correctly bundle the FIDO2 libraries, which can result in being prompted for a passphrase at boot despite the Yubikey being present.

If you encounter this after rebooting, the recovery key you generated earlier will unlock the drive. From a working system, the options are:

Option 1: Use dracut instead of initramfs-tools. Dracut has better FIDO2 support but requires replacing the default initramfs toolchain, which is a significant change.

Option 2: Use fido2luks as a keyscript. This uses fido2-tools directly as a keyscript in the initramfs, bypassing the systemd integration. It is more reliable on Ubuntu-based systems but requires manual setup.

Option 3: Fall back to HMAC-SHA1 challenge-response. The older method used by the yubikey-luks package, which is more reliably supported in the Ubuntu initramfs. Less elegant, but it works.

The situation is improving as Ubuntu’s systemd version catches up. Check the current state before committing to an approach, as the picture may have changed since this was written.

Enrol the backup Yubikey

Once the primary Yubikey is working correctly, enrol the backup key into the same LUKS slot:

sudo systemd-cryptenroll --fido2-device=auto $LUKS_DEVICE

Run this again with the backup Yubikey inserted instead of the primary. Each key gets its own token entry in the LUKS header.

Verify both are enrolled:

sudo cryptsetup luksDump $LUKS_DEVICE | grep -A3 "Tokens"

Testing

Before relying on this configuration, test it with the machine on and the console accessible. Do not test for the first time during an unattended reboot.

Reboot with the Yubikey inserted. At the boot unlock prompt, the system should detect the FIDO2 token and either unlock automatically or prompt for the FIDO2 PIN. Touch the key when it flashes.

If it falls back to asking for the passphrase, the initramfs configuration has not picked up the FIDO2 libraries correctly. Use the recovery key or your existing passphrase to log in and investigate.

Removing the passphrase slot

Once you have confirmed the Yubikey unlocks the drive reliably, and you have the recovery key safely stored, you may choose to remove the original passphrase slot. This makes the Yubikey (or recovery key) the only unlock methods.

List the current keyslots:

sudo cryptsetup luksDump $LUKS_DEVICE | grep "Keyslot"

The passphrase is typically in slot 0. Remove it:

sudo cryptsetup luksKillSlot $LUKS_DEVICE 0

You will be prompted to authenticate with an existing credential before the slot is removed. This is a one-way operation. Be certain the Yubikey and recovery key both work before removing the passphrase slot.

Do not remove the passphrase slot until you have tested Yubikey unlock at least twice across separate reboots, and confirmed the recovery key also works. Removing the passphrase without verified alternatives is how people lose access to their own drives.