From ArchWiki
Jump to: navigation, search

The Yubikey is a small USB token that generates One-Time Passwords (OTP). It is manufactured by Yubico.

One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.


How does it work

Yubikey's authentication protocol is based on symmetric cryptography. More specifically, each Yubikey contains a 128-bit AES key unique to that device. It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc. The OTP is made from concatenating the ID of the key with this encrypted token.

This OTP is sent to the target system, to which we want to authenticate. This target system asks a validation server if the OTP is good. The validation server has a mapping of Yubikey IDs -> AES key. Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP. If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent replay attacks...), then authentication is successful.

The validation server sends that authentication status back to the target system, which grants access or not based on that response.

Security risks

AES key compromise

As you can imagine, the AES key should be kept secret. It cannot be retrieved from the Yubikey itself (or it should not, at least not with software). It is present in the validation server though, so the security of this server is very important.

Validation requests/responses tampering

Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server. The target system thus needs to authenticate the validation server. 2 methods are available :

  • HMAC: This is also symmetric crypto, the target server and validation server share a key that is used to sign requests and responses.
  • TLS: Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.

YubiCloud and validation servers

When you buy a Yubikey, it is preloaded with an AES key that is known only to Yubico. They will not even communicate it to you. Yubico provides a validation server with free unlimited access (YubiCloud). It also offers open-source implementations of the server.

So you can either:

  • choose to use your Yubikey with its preloaded AES key and validate against Yubico's validation server ;
  • or load a new AES key in your Yubikey and run your own validation server.
Note: To authenticate the Yubico validation server, you can:
  • with HMAC: use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID
  • with HTTPS: the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)

Two-factor authentication with SSH

This details how to use a Yubikey to have two-factor authentication with SSH, that is, to use both a password and a Yubikey-generated OTP.


Install yubico-pam.

Note: If you are configuring a distant server to use Yubikey, you should open at least one additional, rescue SSH session, so that you are not locked out of your server if the configuration does not work and you exit your main session inadvertently
Note: The following assumes you're using the default Yubico servers. See the yubico-pam documentation for options relevant to using your own server.


Authorization Mapping Files

A mapping must be made between the YubiKey token ID and the user ID it is attached to. There are two ways to do this, either centrally in one file, or individually, where users can create the mapping in their home directories. If the central authorization mapping file is being used, user home directory mappings will not be used and the opposite applies if user home directory mappings are being used, the central authorization mappings file will not be used.

Central authorization mapping

Create a file /etc/yubico/authorized_yubikeys, the file must contain a user name and the Yubikey token ID separated by colons (same format as the passwd file) for each user you want to allow onto the system using a Yubikey.

The mappings should look like this, one per line:

<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...

You can specify multiple key tokens to correspond to one user, but only one is required.

Per-user authorization mapping

Each user creates a ~/.yubico/authorized_yubikeys file inside of their home directory and places the mapping in that file, the file must have only one line:

<user name>:<Yubikey token ID1>:<Yubikey token ID2>

This is much the same concept as the SSH authorized_keys file.

Note that this file must be readable by the pam_yubico module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.

Obtaining the Yubikey token ID (a.k.a. public ID)

You can obtain the Yubikey token ID in several ways. One is by removing the last 32 characters of any OTP (One Time Password) generated with your Yubikey. Another is by using the modhex calculator.

Enter your Yubikey OTP and convert it, your Yubikey token ID is 12 characters and listed as:

Modhex encoded: XXXXXXX

PAM configuration

Having set up the pam_yubico module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.

The default way

Obtain HMAC credentials from Yubico as described in #YubiCloud and validation servers. You will receive a Client ID and a secret key.

Add one of the two following lines to the beginnning of /etc/pam.d/sshd:

auth            required      pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys

if you're using a central authorization mapping file, or

auth            required      pam_yubico.so id=CLIENTID

if you're using per-user authorization mapping, where CLIENTID} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.

Note: This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the urllist parameter.
Using pure HMAC to authenticate the validation server

Add key to the above lines in /etc/pam.d/sshd:

auth            required      pam_yubico.so id=CLIENTID key=SECRETKEY ...

where CLIENTID and SECRETKEY are your HMAC ID and key.

You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:

# chmod o-r /etc/pam.d/sshd
Note: HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own
Using pure HTTPS to authenticate the validation server
Warning: While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.

If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting CLIENTID=1 instead of your own ID. Although pam_yubico's default server uses HTTPS already, for security reasons you should specify it manually via the urllist parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the debug parameter to the auth line.

SSHD configuration

You should check that /etc/ssh/sshd_config contains these lines and that they are not commented. The sshd_config shipped with openssh has these set correctly by default.

ChallengeResponseAuthentication no
UsePAM yes

That is it!

You should not need to restart anything if you did not change the SSHD config file.

To log in, at the Password: prompt of SSH, you have to type your password without pressing enter and touch the Yubikey's button. The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.

You can display information about the login data generated by pam_yubico by adding the debug option to the auth line in/etc/pam.d/sshd. However, if you're using a central authorization file, you should remove that option once finished testing, as it causes pam_yubico to display the entire content of the central file to every user who logs in using a Yubikey.


This works because the prompt is pam_yubico.so's one, since this module is before pam_unix.so, which normally does basic password authentication. So, you are giving a string that is the concatenation of your password and the OTP to pam_yubico.so. Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password. It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator pam_unix.so is instructed to try receiving a password from the previous module with try_first_pass, so it automatically uses the password sent by pam_yubico.so.

Installing the OATH Applet for a Yubikey NEO

These steps will allow you to install the OATH applet onto your Yubikey NEO. This allows the use of Yubico Authenticator in the Google Play Store.

Note: These steps are only for NEOs with a firmware version <= 3.1.2. The current generation NEOs (with U2F) come with the OpenPGP applet already installed)

Configure the NEO as a CCID Device

  1. Install yubikey-personalization-gui (yubikey-personalization-gui-gitAUR).
  2. Add the udev rules and reboot so you can manage the YubiKey without needing to be root
  3. Run ykpersonalize -m82, enter y, and hit enter.

Install the Applet

  1. Install gpshellAUR, gppcscconnectionpluginAUR, globalplatformAUR, and pcsclite.
  2. Start pcscd with sudo systemctl start pcscd.service.
  3. Download the most recent CAP file from the ykneo-oath site.
  4. Download gpinstall.txt from GitHub.
  5. Edit the line in gpinstall.txt beginning with install -file to reflect the path where the CAP file is located.
  6. Open a terminal and run gpshell <location of gpinstall.txt>
  7. Ideally, a bunch of text will scroll by and it ends saying something like
 Command --> 80E88013D7C000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A
Wrapped command --> 84E88013DFC000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A
Response <-- 009000
Command --> 80E60C002107A000000527210108A00000052721010108A000000527210101010003C901000000
Wrapped command --> 84E60C002907A000000527210108A00000052721010108A000000527210101010003C9010000B4648127914A4C7C00
Response <-- 009000
  1. Unplug the NEO and try it with the Yubico Authenticator app

(Optional) Install the Yubico Authenticator Desktop client

You can get the desktop version of the Yubico Authenticator by installing yubico-yubioath-desktopAUR or yubico-yubioath-desktop-gitAUR.

While pcscd.service is running, run yubioath-gui and insert your Yubikey when prompted.

Enabling U2F in the browser


In order for the U2F functionality to work with Chromium you need to install the libu2f-host library. This provides the udev rules required to enable access to the Yubikey as a user. Yubikey is by default only accessible by root, and without these rules Chromium will give an error.


To enable U2F support in Firefox, you need to install this addon. Native support is currently work in progress.

Enabling OpenPGP smartcard mode

These steps will allow you to use the OpenPGP functionality of your YubiKey.

  1. Configure your YubiKey as a CCID device as mentioned above.
  2. Install pcsc-tools,ccid and libusb-compat
  3. Enable and start pcscd with sudo systemctl enable pcscd.serviceand sudo systemctl start pcscd.service
  4. To verify that your YubiKey is ready to be used run pcsc_scan which will provide some informations about the connected device. Further you can use gpg --card-status to verify that GPG can interact with the card.

Yubikey and KeePass

Yubikey can be integrated with KeePass using plugins.


Restart, especially if you have completed updates since your Yubikey last worked. Do this even if some functions appear to be functioning.

Yubikey not acting as HID device

Add udev rule as described in article

$ sudo echo 'KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="users", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="f1d0"' | sudo tee /etc/udev/rules.d/10-security-key.rules
$ udevadm trigger

You may also need to install the package libu2f-host if you want support in chrome.