Yubico Security Key: Local 2FA with PAM

Yubico Security Key: Local 2FA with PAM

Some time ago, we compared the YubiKey 4C and the Nitrokey Pro which we both use on a daily basis. This time, we show you how you can use a Yubico Security Key with the pluggable authentication module (PAM) on Linux for local two-factor authentication (2FA).

Contents

  1. What is U2F, FIDO and FIDO2?
  2. Requirements
  3. Step 1: Download and install pam_u2f
  4. Step 2: Use pamu2fcfg to generate your config
  5. Step 3: Update your PAM file
  6. Optional: Add a second U2F key
  7. Alternative: Nitrokey FIDO U2F
  8. Summary
  9. Links

Always stay in the loop!
Subscribe to our RSS/Atom feeds.

What is U2F, FIDO and FIDO2?

Universal 2nd Factor (U2F) is an open authentication standard originally developed by Yubico and Google and now hosted by the FIDO Alliance. Security devices with U2F support allow you to use two-factor authentication more easily since they contain a secret key which can provide a second factor only by pressing the device’s button. You don’t need to manage more credentials. We listed further benefits in our last article about security tokens.

The Fast IDentity Online Alliance (FIDO Alliance) consists of different companies which recognized that security tokens for strong authentication lack interoperability. Their aim is to provide widely-accepted specifications to make the usage of online services more secure. The FIDO Alliance published two different specifications:

  • UAF: Universal Authentication Framework (no passwords or user interaction involved)
  • U2F: Universal 2nd Factor (using a security token as a second factor)

Another project of the FIDO Alliance is FIDO2. FIDO2 connects the upcoming Web Authentication standard (WebAuthn) with FIDO’s Client-to-Authenticator Protocol (CTAP). The goal is to enable users to authenticate to online services by using their security devices (mobile and desktop).

To put it in a nutshell, U2F enables two-factor authentication to strengthen existing password-based logins while FIDO2 will enable global passwordless authentication (UAF) or two-factor authentication (U2F) as before.

Requirements

For this tutorial, you need:

  • a Yubico Security Key (or another U2F security token)
  • your Linux device (we use Arch Linux in this guide)

Step 1: Download and install pam_u2f

First of all, we have to install pam-u2f. This is a PAM module which implements U2F. You can use this module for all U2F security tokens not only for YubiKeys. Arch users can install it using AUR: $ aurman -S pam_u2f. This also installs Yubico’s U2F Server and Host C libraries (libu2f-host and libu2f-server).

At this point, you can check whether your system recognizes the YubiKey: $ dmesg | grep -i "Yubico Security Key". This shows “… USB HID v1.10 Device [Yubico Security Key by Yubico] …”. If your device doesn’t recognize the YubiKey, reboot it.

Step 2: Use pamu2fcfg to generate your config

After installing pam-u2f, you can use pamu2fcfg to easily generate a configuration file which we will add to the PAM configuration later.

Enter $ pamu2fcfg. The physical button of the Security Key blinks now. Press the button of the YubiKey to proceed. You will immediately see an output like “[username]:[key-handle],[public-key]” in your terminal.

Open your favorite text editor and save this output in a file which is accessible for the user (e.g. in the home folder of the user). We will put it in ~/.config/Yubico/u2f_keys since there is already a Yubico folder and u2f_keys is the default location for this PAM module’s auth file.

Advanced users can directly redirect the output of pam-u2f to the file by entering: $ pamu2fcfg > ~/.config/Yubico/u2f_keys.

Step 3: Update your PAM file

Finally, we have to tell PAM to use our U2F security key. You can either create a new file in /etc/pam.d/ or edit an existing file. We will edit /etc/pam.d/gdm-password here to use U2F with the GNOME Display Manager (GDM).

Add auth sufficient pam_u2f.so debug to the file and save it.

  • debug: This enables debug output if there are any errors
  • sufficient: This is a PAM keyword telling PAM that if this module succeeds, all following sufficient modules are also satisfied. In our case, PAM will accept:
    • only our password (single factor)
    • only our U2F token (single factor)
    • both factors (if the U2F token is connected with the device when GDM asks for the password)

Log out and test if you can log in with your U2F key and/or password.

If you can successfully log in, change the previously entered string to auth required pam_u2f.so. This enforces usage of the U2F token and enables true two-factor authentication.

Optional: Add a second U2F key

There is the risk of losing or destroying the U2F token. We recommend to use a second one as a backup. You have to run step 2 again but this time you press the button of the backup device.

Change the string in ~/.config/Yubico/u2f_keys to “[username]:[key-handle],[public-key]:[backup-key-handle],[backup-public-key]” and test it again.

Alternative: Nitrokey FIDO U2F

In summer 2017, Nitrokey UG announced that they will release their new Nitrokey FIDO U2F with support for U2F soon. However, they postponed the release several times. Since November 2018, the Nitrokey FIDO U2F is available. Check our comparison of both U2F tokens.

Follow us on Mastodon:
@infosechandbook

Summary

In this article, we showed one of many examples for using a U2F security token. The upcoming WebAuthn standard has the potential to spread acceptance of such tokens on the internet making credential management less painful. We will show you more examples in upcoming articles.

You can also check open-source projects like the upcoming Solokeys or the Nitrokey FIDO U2F (if ever available) if you don’t want to buy YubiKeys. Most U2F-only tokens cost about € 20.

Changelog

  • November 3, 2018: Updated information about Nitrokey FIDO U2F.

See also