Thomas' Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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 [[public:managing_luks_on_debian|]].

===== On the Yubikey =====

You must set up your Yubikey with the [[https://docs.yubico.com/yesdk/users-manual/application-otp/how-to-program-a-challenge-response-credential.html|challenge-response algorithm]] in slot 2. One of the methods of doing so is using Yubico Authenticator.
{{:public:yubikey_challenge-response.png|}}

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.

===== On the Debian system =====
First, become root and install ''yubikey-luks'':

<code bash>
su -
sudo apt install yubikey-luks
</code>

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''

<code bash>
yubikey-luks-enroll
</code>

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:
<code>
sda3_crypt UUID=3d5a01bc-42dc-4ed8-9e61-caa3be6c66a1 none luks,discard
</code>
After:
<code>
sda3_crypt UUID=3d5a01bc-42dc-4ed8-9e61-caa3be6c66a1 none luks,discard,keyscript=/usr/share/yubikey-luks/ykluks-keyscript
</code>

Finally, update your initramfs:
<code bash>
update-initramfs -u
</code>

===== 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:
<code bash>
cryptsetup luksDump /dev/sda3
</code>
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:
<code bash>
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).
</code>
Use that as a passphrase to allow us to remove the key from slot 0:
<code bash>
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.
</code>

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.

===== Optional: bypass the passphrase =====
:!: 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:

<code bash>
YUBIKEY_CHALLENGE="your passphrase here"
</code>

Then, update your initramfs again:
<code bash>
update-initramfs -u
</code>

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

{{tag>Debian LUKS Yubikey}}