This is an old revision of the document!
Table of Contents
Unlocking Debian LUKS with a Yubikey at boot
On the Yubikey
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.
On the Debian system
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).
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
Try it out
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).
Removing the regular password
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 and passphrase will be able to unlock the disk!