Yubikeys Part. 1

Recently bought a pair of YubiKeys (YubiKey 5C specifically), after years of thinking about it in the back of my head…

The initial idea was a single post for my YubiKey setup, but became it too long, so it will be a 2-parter:

• Part 1: YubiKey basics and authentication for local Linux machines.
• Part 2: Authentication for SSH, and GPG.

Note: All configuration is done in Fedora with GNOME DE (applicable 1-to-1 on related distros) and YubiKey 5C / USB (not the Biometric version).

What is a YubiKey?

According to Wikipedia, the ultimate source of truth:

YubiKey is a small hardware device that can “protect access to computers, networks, and online services that supports one-time passwords (OTP), public-key cryptography, authentication, and the Universal 2nd Factor (U2F) and FIDO2 protocols developed by the FIDO Alliance. It allows users to securely log into their accounts by emitting one-time passwords or using a FIDO-based public/private key pair generated by the device.

Managing YubiKeys

Install Required Packages

The yubikey-manager package provides the ykman CLI tool to manage all YubiKey applications, such as Yubico OTP, FIDO U2F, FIDO2, OATH, PIV, OpenPGP, and YubiHSM Auth.

# Install the "yubikey-manager" package
sudo dnf install yubikey-manager

General Commands

# Show YubiKey information (firmware, serial, applications)
ykman info

# List connected YubiKeys
ykman list

# Enable applications (such as, FIDO2, PIV, etc.)
ykman config usb --enable <application_name>

# Disable applications (such as, FIDO2, PIV, etc.)
ykman config usb --disable <application_name>

FIDO Commands

Manage FIDO2/U2F authentication (used for local Linux authentication).

# Show FIDO information (PIN, credential count)
ykman fido info

# Change or set FIDO2 PIN (required if using PIN verification)
ykman fido access change-pin

# Verify existing FIDO2 PIN (if already set)
ykman fido access verify-pin

# Unlock FIDO (after too many failed PIN attempts)
ykman fido access unlock

# List resident credentials
ykman fido credentials list

# Delete a credential
ykman fido credentials delete

# Reset FIDO (WIPES ALL FIDO DATA)
ykman fido reset

PIV Commands

Smart card functionality for certificates, authentication, signing.

# Show PIV information
ykman piv info

# Change PIN (default: 123456)
ykman piv access change-pin

# Change PUK (PIN Unblocking Key, default: 12345678)
ykman piv access change-puk

# Change management key
ykman piv access change-management-key

# Generate key in slot
ykman piv keys generate 9a /path/to/public.pem

# Import certificate
ykman piv certificates import 9a /path/to/cert.pem

# Export certificate
ykman piv certificates export 9a /path/to/output.pem

# Generate self-signed certificate
ykman piv certificates generate 9a

# Reset PIV application (WIPES ALL PIV DATA)
ykman piv reset

GPG Commands

# Show OpenPGP information
ykman openpgp info

# Change User PIN (default: 123456)
ykman openpgp access change-pin

# Change Admin PIN (default: 12345678)  
ykman openpgp access change-admin-pin

# Set reset code for PIN recovery
ykman openpgp access set-reset-code

# Reset OpenPGP application (WIPES ALL PGP DATA)
ykman openpgp reset

Using YubiKey for Local Linux Authentication

Configure your Linux machine to authenticate/login with just a touch of the YubiKey, no password needed.

Install Required Packages

• pam-u2f provides the PAM module that handles YubiKey authentication.
• pamu2fcfg is the configuration tool we’ll use to register our keys with the system.

sudo dnf install pam-u2f pamu2fcfg

Register Your YubiKey(s)

Before we can use the YubiKey for local authentication, register it with the system.

First, plug the YubiKey to your machine and run pamu2fcfg. When you run pamu2fcfg, the YubiKey will start blinking. Touch the metal contact to complete the registration.

# Create the YubiKey configuration directory
mkdir -p ~/.config/Yubico

# Register your YubiKey (plug it in first and touch the device)
pamu2fcfg > ~/.config/Yubico/u2f_keys

If you have a backup YubiKey, register it here too:

# Add additional backup YubiKeys to the same file (append >>)
pamu2fcfg -n >> ~/.config/Yubico/u2f_keys

Secure your u2f_keys file to prevent unauthorized access.

chmod 600 ~/.config/Yubico/u2f_keys

Important Notes:

• The above key registration is for the current user only.
• For system-wide YubiKey registration, register the key in the /etc/Yubico/u2f_keys file instead with each user entry per line.
• Backup the u2f_keys file to a secure location.

Configuring PAM Authentication

Now its time to configure PAM (Pluggable Authentication Module) to authenticate with the YubiKey. PAM can be scary like a molester in the park, but we’ll make it easy.

PAM controls how authentication works on Linux, so we’ll modify a few configuration files to make that happen.

Common Configuration Options

Authentication Modes

Common Options:

Configure sudo Access

Edit /etc/pam.d/sudo to configure YubiKey authentication when usingsudo.

# Contents of "/etc/pam.d/sudo"
# Add a line like this before any existing auth lines (use 'required' or 'sufficient' authentication mode and use whichever options you prefer)
auth		required		pam_u2f.so cue

For example, a complete /etc/pam.d/sudo file would look like this:

# Contents of "/etc/pam.d/sudo"
#%PAM-1.0
auth		sufficient		pam_u2f.so cue pinverification=1
auth		include			system-auth
account		include			system-auth
password	include			system-auth
session		include			system-auth

Important:

• My recommendation is to have the options cue pinverification=1 to authenticate by touching the YubiKey and providing the PIN, which is much more secure than just touching the key.
• The order of PAM modules is important, keep an eye on it.
• Test sudo access in a separate terminal before closing your current session to prevent misconfigurations that could lock yourself out. Start with sufficient authentication mode if you don’t know what you are doing.

Additional Configurations

You can apply the same configuration on other authentication points as well:

• /etc/pam.d/gdm-password
  • Authenticate for the graphical login (GDM - GNOME Display Manager).
  • Allows unlocking your desktop with just a YubiKey touch.
• /etc/pam.d/login
  • Authenticate for console login.
• /etc/pam.d/polkit-1
  • Authentication for GNOME privilege elevation prompts (like systemctl).
  • These prompts are controlled by polkit, not the regular PAM authentication.

Note on the GNOME Keyring: By default, YubiKey will not unlock the GNOME Keyring. This is because the keyring is encrypted with your user password, and the YubiKey doesn’t provide that password to PAM. To override this, you can set a blank password for the keyring, but I personally don’t recommend this, just keep the keyring password protected, it’s more secure.

What’s Next?

YubiKeys are easy to setup and offer great security. Just make sure you don’t lose them and have a backup key registered in case something happens.

For me however, they don’t replace 2FA from TOTP applications. They are a compliment due to its ease of use.

Next post will be YubiKeys setup for SSH and GPG authentication.