Yubikey and PAM

This post assumes you are using a recent Ubuntu or similar Debian derivative with apt as your package manager. It is also assumed that your Yubikey is in a mode that supports FIDO/U2F. It should do so out of the box, unless you configured it otherwise.

If you have no clue what PAM is, this ancient article may be as good as any to get you started.

For a description of the different supported modes and how to switch to them see this page. Or you could just install yubikey-personalization instead and read man ykpersonalize. ;)

This guide is intended for use with your system locally and will NOT work over ssh. I will write a separate guide for that.

sudo apt-get install libpam-u2f

If you are running Ubuntu you may want to prefer the more update version from the official Yubico PPA. In that case add it first.

sudo add-apt-repository ppa:yubico/stable && sudo apt-get update

Don't forget to press enter when prompted to confirm adding the PPA.

Next, insert your Yubikey into a free USB port on your machine. Then create the following directory. If the directory already exists, you may ignore the resultant error.

mkdir ~/.config/Yubico

Next run the following command, the Yubikey should begin flashing, touch the metal contact to confirm the add.

pamu2fcfg > ~/.config/Yubico/u2f_keys

Add additional Yubikey devices as follows:

pamu2fcfg -n >> ~/.config/Yubico/u2f_keys

Now we can use the token in two different ways. As an example we use the sudo command here. But this can be done for login as well. For a longer more in-depth guide you can always refer to the Yubico site directly.

1FA - one factor authentication

IF the Yubikey is present, touching it will suffice instead of a password to authenticate for sudo use. If the key is not present then a password will be required. Note, whether you feel this is secure enough or not is your judgement call. I make no recommendation either way here.

sudo vi /etc/pam.d/sudo

In the file insert the following below the last line starting with "session" and above the first line starting with "@include".

auth       sufficient   pam_u2f.so

2FA - two factor authentication

In this instance the Yubikey must be present for sudo use to succeed. The system will first ask you for your password. After that the inserted Yubikey will begin flashing. Only after you then touch the key will sudo succeed.

Be careful here, if you lose and don't have a second Yubikey registered you can screw yourself quite a bit and would have to jump through some hoops to get control back. E.g. boot from a live USB stick, mount your machine's file system, edit /etc/pam.d/sudo to comment out or remove the auth rule.

So to achieve the above 2FA implementation:

sudo vi /etc/pam.d/sudo

Then insert the following line below the "@include common-auth" statement:

auth       required   pam_u2f.so

Challenge Response

You may prefer to go with a more sophisticated challenge response setup instead. The official Yubico guide for this is can be found here.

Note though that their guide will configure the key such that no human interaction is required to respond for the challenge, i.e. the key just needs to be plugged in but not touched. The YubiKey Manager CLI (ykman) tool has the option to configure the key to require touching before the challenge response is returned should you so wish. To activate this function add the "-t" flag before the the "-g" flag in section 3 step 3 of their guide. For a full description of the ykman tool see here.