This is a pretty short guide on how to get U2F thumbdrives configured for Arch Linux logins. Most of it is copied from the source: Yubico on GitHub. I've made a few changes that are specific to Arch Linux, but realize that most of the work here was on Yubico.

Even better, another shoutout goes to maxime1986 for creating the AUR package that makes installing the pam-u2f PAM module that much easier.


One more thing: DO NOT PLACE THE MAPPINGS FILE IN AN ENCRYPTED HOME DIRECTORY AS YOU WILL NOT BE ABLE TO LOG IN! The login process will decrypt the home directory, but since the file to authenticate against is encrypted...well, you get the picture.

sudo Configuration

If you're using the Defaults rootpw option in your /etc/sudoers file, this will cause sudo not to work with the pam_u2f module. The Defaults rootpw line forces sudo to authenticate against the root user which screws up how pam_u2f authenticates against the u2f_mappings file.

Also, don't use Defaults rootpw in your sudoers file. It kinda defeats the purpose of sudo.

Things That Work

After some feedback, here are things that will work with the security key:

  • Logging in to the computer (console)
  • Privilege elevation via sudo
  • GDM login screen/lock screen
  • i3 login screen/lock screen
  • KDE Plasma/klockscreen

Things that don't (verified):

  • SSHing into a server configured via this guide. OpenSSH hasn't yet implemented the required code for this to work.

Things You Need

Here is a long list of things you will need:

  1. At least one U2F key. I tested this using a Yubikey 4 and a Yubikey 4 Nano.
  2. Arch Linux installed.


These steps assume that you're using an AUR package manager. This is mostly due to my overall laziness on rewriting to build packages directly. The AUR package manager in use in this guide is pacaur. Also, it assumes that you have the base-devel package installed.

Also, this guide uses the centrally-managed pam_u2f configuration where user-key relations are stored in /etc/u2f_mappings.

Install pam_u2f

  1. Ensure that all of the U2F keys are removed from the computer.
  2. Install the pam_u2f package via the pacaur command. This should bring in the libu2f-host, libu2f-server, and the asciidoc packages.
  3. pacaur -S pam_u2f

Generate /etc/u2f_mappings File

  1. Insert the U2F key into the laptop.
  2. Using the pamu2fcfg command, grab the U2F key's information so we can add it to the u2f_mappings file. After running the command, ensure that you actually touch the U2F key. Also, the command is pamu2fcfg -ujweatherly, simply replace jweatherly with your login username.
    pamu2fcfg -ujweatherly
  3. Open the /etc/u2f_mappings file and add the line generated in the previous step to this file. If the output from the pamu2fcfg command ends in a % sign, ensure that you don't copy the % into the file.

    If you have more than one key that you'd like to associate with a given user, simply add the information you grabbed via the pamu2fcfg command to the end of the line. Remember that each key is seperated by a :.


Configure PAM (Test Run)

  1. Navigate to the /etc/pam.d directory.
  2. Open the system-auth file and add the following line to the top of the auth section. The reason that the sufficient line is there is that if the u2f_mapping file is messed up then you'll be able to log on via password. Also, the line below is all on one single line. Unfortunately, this will look like two lines on some browsers.

    auth  sufficient  debug authfile=/etc/u2f_mappings cue

    This should make the first few lines of the system-auth file look like so:

  3. Reboot the computer.

  4. When the login screen is loaded, it should ask you to touch the device. Simply touch the device and you should be able to log in. If this works, proceed to the next section. If not, log in via your regular password and try to sudo -i. The pam_u2f module is set to debug mode and should give good information on what went wrong.

Finishing Up (Final Run)

  1. Navigate to the /etc/pam.d directory.
  2. Open the system-auth file again, and change the auth section to look like the following. We're basically moving the pam_u2f module down after the password, and making it required. Also, let's remove the debug portion.

  3. Change the permissions of the /etc/u2f_mappings file to something a bit more secure. If you're running KDE as your desktop, you will have to loosen those permissions up to 444. Failure to do this will make kcheckpass very unhappy.

    chmod 400 /etc/u2f_mapping
  4. Reboot and enjoy the two factor goodness of being able to log in via your token.

  • Added KDE/kcheckpass information to the guide.
  • Happy New Year!
  • Added Things That Work and Things That Don't Work sections to the guide.
  • Added warning for /etc/sudoers configuration settings involving Defaults rootpw.
  • Fixed stubborn language highlighting and fenced code block issue by hand-jamming HTML instead of Markdown for this guide.
  • Fixed theme issues relating to the new language highlighting stuff.
  • Fixed theme CSS issues.
  • Cleared up phrasing on the pamu2fcfg command.
  • Updated encryption information.
  • Added chmod command to the /etc/u2f_mappings file.
  • Minor grammatical changes.
  • Replaced system-auth with images (better layout)
  • Changed header image