Unlocking Debian LUKS with a Yubikey at boot

You can use a Yubikey to unlock a Debian system at boot. For general info on managing LUKS, see Managing LUKS on Debian.

You must set up your Yubikey with the challenge-response algorithm in slot 2. One of the methods of doing so is using Yubico Authenticator.

Note that, when setting up the challenge-response algorithm, you will be asked to enter a secret key. This key is at the heart of this method. Any Yubikey that has the same key set, will be able to generate the same responses to your challenges. Make sure it remains secret! During setup you can also determine if the key requires to be touched for the response to be generated.

First, become root and install yubikey-luks:

su -
sudo apt install yubikey-luks

Next, enroll your Yubikey. By default, the enrollment command will detect your boot disk and will save the new credential in LUKS slot 7, but you can adjust this. See man yubikey-luks-enroll

yubikey-luks-enroll

Follow the on-screen instructions. You will also be asked to enter a passphrase. This passphrase will be used in the challenge-response algorithm, and will still be needed at boot. This way, to unlock your disk, you will need something you have (the Yubikey) and something you know (the passphrase). Also note that the PIN of your Yubikey will not be asked when unlocking the disk. The passphrase already fulfills this purpose.

Then, adjust /etc/crypttab and append the keyscript parameter to refer to the ykluks keyscript.

Before:

sda3_crypt UUID=3d5a01bc-42dc-4ed8-9e61-caa3be6c66a1 none luks,discard

After:

sda3_crypt UUID=3d5a01bc-42dc-4ed8-9e61-caa3be6c66a1 none luks,discard,keyscript=/usr/share/yubikey-luks/ykluks-keyscript

Finally, update your initramfs:

update-initramfs -u

When you know reboot the system, you will be asked to insert a Yubikey and enter a passphrase. After doing so, you may need to touch the Yubikey before the challenge-response process is completed, depending on how you've set up your Yubikey. This process should now successfully unlock your disk at boot time.

Do note that the regular password you used before to unlock the disk also still works. But that can now be removed (if you're sure that unlocking with the Yubikey is working properly).

Only do this when you're sure that unlocking with the Yubikey is working properly! If not, you may not be able to unlock your disk after doing this.

You can check what LUKS slots are in use by executing the following command:

cryptsetup luksDump /dev/sda3

The newly registered slot for the Yubikey is slot 7 (if you didn't change that explicitly when enrolling). We can now delete other slots, e.g. the regular password in slot 0.

However, deleting the key in slot 0 will require us to confirm that we know the key for slot 7, so we'll need to generate that once, to enter in the confirmation prompt. We can do so with yubikey-luks-open -v. The entire process is shown below.

Determine the challenge-response result to find the LUKS key:

yubikey-luks-open -v
debugging enabled
This script will try opening yubikey-luks LUKS container on drive /dev/sda3 . If this is not what you intended, exit now!
Please insert a yubikey and press enter.
Enter password created with yubikey-luks-enroll:
Password: verysecret
Yubikey response: 96e4d77c1c68871c550d8ec729f557c10034eb29
LUKS key: 96e4d77c1c68871c550d8ec729f557c10034eb29
Cannot use device /dev/sda3 which is in use (already mapped or mounted).

Use that as a passphrase to allow us to remove the key from slot 0:

cryptsetup -v luksKillSlot /dev/sda3 0
Keyslot 0 is selected for deletion.
Enter any remaining passphrase: 
Key slot 7 unlocked.
Key slot 0 removed.
Command successful.

Now, only the combination of your Yubikey (or any other Yubikey with the same secret key) and passphrase will be able to unlock the disk! Make sure that you either have multiple Yubikeys with the same secret key , or that you have multiple Yubikeys with different secret keys enrolled. Otherwise you may lose all your data when a key breaks or is lost.

If you bypass the passphrase, you'll only rely on something you have, and not something you know. I strongly advise against this as it is less secure, but it can be preferred in some environments where interaction is not feasible.

Open /etc/ykluks.cfg and append the following line:

YUBIKEY_CHALLENGE="your passphrase here"

Then, update your initramfs again:

update-initramfs -u

https://packages.debian.org/unstable/yubikey-luks
https://www.endpointdev.com/blog/2022/03/disk-decryption-yubikey/