I recently acquired a Yubikey Neo - a nifty little hardware second factor authentication device. It's primarily intended for use with One Time Passwords, and the emerging U2F protocol - but since Yubikey version 2 it also supports HMAC-SHA1 challenge-response authentication. HMAC-SHA1 combines a secret key (stored inside the Yubikey) and combines this with a passphrase to generate a response.

How can I combine the Yubikey with my Ubuntu FDE setup to use 2FA with my encrypted hard drive?

up vote 26 down vote accepted

A group called PrivacyIdea have created a little package to add a HMAC-SHA1 challenge-response routine to the initramfs, which means that Ubuntu can query you for a challenge to pass to the Yubikey and then use the response to unlock the LUKS volume. For the most part, I'm following these instructions, with some added comments. The process is actually very easy to do.

I've tested this on Ubuntu 14.04, 16.04 and 18.04; using a Yubikey Neo. It should work with any recent Yubikey, with firmware 2.0+, and with any version of Ubuntu after 14.04. There could also be other hardware HMAC-SHA1 challenge-response devices that this works with, but I'm not aware of any that exist. As always, make sure you have a backup of your data before proceeding - there shouldn't be any issues here, but there's always the chance this will destroy everything on your computer. These instructions come with no warranty.

Update: Since Ubuntu 16.04, the needed packages are in the main repositories and no PPA is needed.

Add a comment if you have questions!


0. Prerequisites

For this to work, you will already have to have LUKS full-disk encryption set up and working. You can do this by selecting the appropriate option when installing Ubuntu. For maximum security, you should have a chosen very strong passphrase during the install. If your passphrase isn't up to scratch, you should change it to a better one before continuing (more detailed instructions here).

The method below will not replace any existing passphrases, but will instead add another passphrase to one of the LUKS slots. Hence if you lose your Yubikey you can still unlock your computer using any existing passphrase - I suggest you make a note of it and hide it away somewhere safe - you will also need it a few times during this procedure. Your new Yubikey challenge passphrase should still be reasonably strong, but doesn't have to be as long as the passphrase you used when installing Ubuntu.


1. Add PrivacyIdea PPA and install package

On Ubuntu 14.04

Open a terminal, and run the following command:

sudo add-apt-repository ppa:privacyidea/privacyidea 

Press Enter when prompted, then run:

sudo apt-get update

Then install the package with:

sudo apt-get install yubikey-luks

On Ubuntu 16.04, 18.04 (and later)

There is no need for a PPA, you can install the package with:

sudo apt-get install yubikey-luks

2. Install Yubikey software

If you are using the HMAC-SHA1 functionality of the Yubikey for something else, you can skip this section. It will erase any configuration in the second Yubikey slot, so don't perform this step if you use HMAC-SHA1 for other purposes with this Yubikey.

You'll need to set up your Yubikey to work with Ubuntu by installing the required software, either from the Yubico PPA on Ubuntu 14.04 or from the main Ubuntu repository on 16.04 and later.

On Ubuntu 14.04

If you have not done so before, add the PPA and install the package with:

sudo add-apt-repository ppa:yubico/stable
sudo apt-get update
sudo apt-get install yubikey-personalization

On Ubuntu 16.04, 18.04 (and later)

sudo apt-get install yubikey-personalization

3. Initialise Yubikey Slot for HMAC-SHA1

Now we need to program the second slot of the Yubikey with a HMAC-SHA1 configuration. This will erase your previous slot configuration, which is empty by default. Again, if you are using HMAC-SHA1 for something else do not issue this command - it will erase your configuration. You can safely use the same secret key inside the Yubikey for this LUKS setup as for your other uses. (For example, with another computer using LUKS+Yubikey).

ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible

The terminal will display some information about the changes made. You don't need to note this down, but it will show the secret key used by the Yubikey in the HMAC-SHA1 algorithm to calculate the response when given a challenge.


4. Enroll Yubikey to LUKS Slot

Now we will edit the LUKS configuration to append the response from the Yubikey as one of the decryption keys.

The partition that we need to specify depends on whether you are using BIOS or UEFI to boot your machine. For BIOS, the encrypted volume is at /dev/sda5 by default, for UEFI it is at /dev/sda3. You can check this by opening the disks utility and confirming the path of the partition - it should either be sda3 or sda5.

Run this in a terminal:

sudo yubikey-luks-enroll -d /dev/sda3 -s 7

This will write to slot 7 of the LUKS configuration, follow the prompts in the installer (they vary slightly depending on which version you're running).

Then you're all done! You should be able to reboot your computer, and if your Yubikey is inserted then you can type in your challenge password and use the Yubikey as a second factor to unlock the LUKS partition and boot the system. Once you've decrypted the hard drive you can remove the Yubikey.

If you lose your Yubikey you can still enter your original (hopefully very long) passphrase to decrypt the hard drive, and then you can follow this procedure again to register a new Yubikey.


Changing the encryption challenge passphrase

Changing the password at a later date is quite simple, just use this command to reset the secret key. It is not entirely necessary to reset the secret key, but it won't hurt. Bear in mind that this will destroy the previous secret key, do not do this if you use HMAC-SHA1 for something else with this Yubikey. (For example, with another computer using LUKS+Yubikey).

 ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible

Then, similar to Step 4, above, to enroll a new password into the LUKS key slot, except opt to clear Slot 7 with this command:

sudo yubikey-luks-enroll -d /dev/sda3 -s 7 -c

When prompted to Enter any remaining passphrase, use your backup passphrase - not the Yubikey challenge passphrase. Then enter a new Yubikey challenge passphrase, twice, then finally you will need to enter the backup passphrase one last time.

Now your old Yubikey challenge passphrase has been removed and only your new one will decrypt the hard drive. Your previous backup passphrase will still be the same. You can change that passphrase by following the links in Step 0.


Note on security implications

Adding a Yubikey will add a certain level of security to your system - someone has to know both the challenge passphrase and have your Yubikey to be able to unlock your hard drive (or find your initial passphrase, which you are now using as a backup). However, it is technically feasible for an attacker to decrypt the hard drive if they know your challenge passphrase (for example, by "shoulder surfing" you while you type it in) and can gain access to your Yubikey for only a short time. Using the challenge passphrase they could get the response from the Yubikey and store it, and then use it to decrypt the hard drive at any time without the Yubikey. Or, again if an attacker or a piece of malware knew your passphrase and was able to run code on a machine connected to your Yubikey they could also issue the challenge and store the response. It is therefore still extremely important to be vigilant when entering your challenge passphrase, and to ensure that you always have the Yubikey in a safe location. You should also only ever plug it into a machine that you trust. If you lose track of your Yubikey and suspect someone may have been using it to try to learn the decryption key, perform steps 2 and 3 again to reset the secret key inside the Yubikey and choose a new challenge passphrase. Note that if an adversary has managed to learn one of your passphrases (either the HMAC-SHA1 response from the Yubikey, or your backup) they could make a backup of the LUKS master key, and then use that to decrypt your hard drive even if you change the passphrase in the future. The man page for cryptsetup explains this, look at the luksHeaderBackup section. If you suspect this has happened then you must make an entirely new LUKS volume to protect your data.

  • Update: I've also tried this with 15.04, it looks like the PPA doesn't have a build of the required package, so I have to change the DEB line in the Software Sources to use the "trusty" repository instead of "vivid". After making this change my LUKS+Yubikey setup now works on 15.04. – seanlano Sep 20 '15 at 13:37
  • 4
    Do not use the privacyidea repo anymore! The package is now contained in upstream debian! – cornelinux Aug 31 '16 at 11:30
  • 1
    There is a way to avoid login without yubikey: change luks passphrase every time when the user logs in. There is implementation for Gentoo here: github.com/flowolf/initramfs_ykfde It can be adapted for Ubuntu within short time. – Dmitry Dulepov Oct 4 '16 at 11:04
  • 1
    I'll guess the same procedure works for the new 18.04 LTS release? – Mark Veenstra May 9 at 7:00
  • 1
    I've tried with Ubuntu 18.04 and it works fine. – jetole Jul 28 at 20:16

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.