Using YubiKeys with Fedora

The packages required for both PAM modules are available in the official repositories.

Next configure PAM to accept a YubiKey as a means of authentication. There are many options in /etc/pam.d to modify and add a YubiKey, but the most common use-cases are:

In a PAM configuration file if using {yubikey,u2f}-sufficient add an include line before or if using {yubikey,u2f}-required add it after a line that reads "auth substack system-auth" or "auth include system-auth". An include of yubikey-sufficient looks like this:

The following example sets a YubiKey OTP as 'sufficient' factor for terminal login. This means that a YubiKey alone is enough to authenticate a user when logging in on a terminal.

Open /etc/pam.d/login with your editor of choice. Find the line that reads "auth substack system-auth". Above that, insert the following:

The result looks similar to this:

Next time you open a console (local, not ssh session) and attempt to login you should be prompted YubiKey for '<user>':. Tap your YubiKey to input an OTP and you will be logged without entering a password.

To add a YubiKey to more than terminal login, like local sshd servers, sudo or GDM login, add the respective auth include to one of the other configuration files in /etc/pam.d.

Newer YubiKeys (YubiKey 2+) have the ability to store two separate configurations. The first is generally used for OTPs, the second for a strong, static password. If the button is pressed shortly, something up to 1.5 seconds, the first configuration is triggered. If the button is pressed longer, in the range of 2.5 to 5 seconds, the second configuration is triggered.

Write a static key using ykman otp static.

A more elaborate example: write a new static key to the second configuration slot using a specific AES key.

This writes a static key to the YubiKey based on the 32-byte AES key specified with the -a option. The -2 option sets the second slot as target. The other two options are a matter of personal taste. The append-cr option sends a carriage return as the last character of the key. That way I do not have to press <ENTER> myself. The -man-update option disables easy updating of the static key in the YubiKey. Enabling this will allow for altering the static password without the use of ykpersonalize.

If we want to write a new configuration to the first slot of the key, we need to specify some more options. If you want to be able to upload you key to Yubico, in order to authenticate against their servers, remember what the values are that you use below. You will need them later on.

The -1 option tells ykpersonalize to use the first configuration. The fixed option specifies the public ID of the YubiKey. This is referred to as the 'prefix' later on, when we go uploading it. The value you use here has to start with 'ff' in hex or 'vv' in modhex (see below). Yubico enforces this when you try to upload your key to their servers. The value for the fixed option can be up to 16 characters in length.

As part of the OTP, you can specify an internal identifier for your key. This is what the uid option does. The value is in plain hex, not modhex and ''exactly'' 12 character long.

The -a option, again, is the 32-byte AES key and append-cr appends a carriage return to my key as the last character.

When you hit the <ENTER> key, the ykpersonalize program will present you with my options and ask for confirmation before continuing:

After pressing 'y', I am able to generate OTPs with my new key!

The Personal Identitiy Verification (PIV) module stores private keys and corresponding certificate files for purposes such as encryption, authentication and signatures. If your YubiKey supports this you want to change the PIN and PUK as well as the Management Key.

Set the PIN.

Set the PUK.

Update the Management Key.

You can now safely use the PIV module to generate private keys and store certificates.

FIDO2 is an open authentication standard and encompasses sub-standards and protocols to either provide two-factor or even passwordless authentication methods.

One interesting use case of the FIDO module to note is storing OpenSSH public-key identities, which modern OpenSSH agents can pick up right away and use. This makes ssh keys quite portable.

If your key supports FIDO change its pin with ykman fido access like this:

The OATH feature provides TOTP and HOTP authentication protocols. It can be protected with a passphrase to access and generate OTP codes. This is different from the Yubico OTP feature, which uses a single stored secret on the YubiKey for challenge-response.

Change the OATH password with:

Configure your device to remember this password so you don’t have to re-enter it anymore.

If the key does not support FIDO2 you have to use an alternative method via the PIV module and PKCS#11.

Create an ED25519 private key inside the PIV module, requiring pin entry upon use and always require a touch of the YubiKey button:

The slot 9a on the key is dedicated to authentication. There are more slots for features like encryption or signing.

Create a certificate in this same slot for the PIV/PKCS#11 library:

Now generate a public key from the X.509 certificate stored on the YubiKey. Other features like resident keys work the same as with the FIDO2 approach, but you have to add the additional option as shown below.

Login to systems with this public key:

The ssh-agent may also load keys from the YubiKey with: