One of the first things I did once I switched to Linux was to look for guides about implementing Yubikey support to the operating system. Integrating Yubikey with Windows was a pain in the ass back then, therefore one of the reasons I’d switched to Linux was that I hoped I could configure Yubikey in Linux without much efforts.

First, we need the following packages:

  • pam-u2f: To authenticate ourselves we will use the U2F protocol
  • yubikey-personalization: If you never configured your Yubikey, I recommend doing so.

Anyway… If you don’t need the personalization tool. Just install pam-u2f:

sudo pacman -Syu
sudo pacman -S pam-u2f

Then insert your Yubikey, issue the command pamu2fcfg > u2f_mappings. When the yellow area on your key blinks, simply touch it. The secret should be automatically outputted to the file u2f_mappings. Move it to a secure location and make sure only root can read it:

sudo cp u2f_mappings /etc/u2f_mappings
sudo chmod 400 /etc/u2f_mappings

We need to modify the pam module to start authenticating with U2F keys. Ideally, we would use U2F for all root actions, to change this once and for all(in Arch based distros), we will change the /etc/system-auth file. Open it with whatever editor you like:

sudo nano /etc/system-auth

Find the line with pam_unix.so and above it, add this line:

auth       sufficient                  pam_u2f.so           authfile=/etc/u2f_mappings	cue

DO NOT CLOSE THE FILE YET

Here sufficient means once this line is satisfied, subsequent modules in the stack will not be parsed, thus allowing for a passwordless authentication. pam_u2f.so is the module we’re using. authfile=/etc/u2f_mappings is the file we just created. cue means you’ll be prompted to touch the key when authenticating:

When U2F fails, pam will fall back to passwords.

Now you can save the file but DO NOT CLOSE IT YET. We need to make sure the key and U2F module works. For nano you can use Ctrl + O to save but leave the file open.

Now open a terminal and issue the command sudo echo test, you will be prompted for the key if you inserted it before issuing the command:

Should you configured correctly, touching the key should echo the message test as root. Now pull the key out, open a new terminal session and issue the same command again:

This time you’re directly asked to enter a password because the key is not inserted beforehand.

This proves you configured correctly, you can safely close the system-auth file. For Arch Linux and Endeavour OS, this allows you to authenticate polkit, login, sudo, lockscreen with your security key. This is slightly different for other distros, I suggest consulting the Yubikey guides for them.