How to Use a YubiKey on Linux

A YubiKey turns physical possession into a second authentication factor. On Linux you can use it in four distinct modes: PIV (smart card for SSH/TLS client auth), FIDO2/WebAuthn (browser logins and sudo), OpenPGP smart card (GPG signing, encryption, SSH via gpg-agent), and OATH (TOTP codes). This guide covers all four, plus the udev rule that makes the key usable without running everything as root.

Install Required Packages

Most functionality lives in a handful of userspace libraries. Install them before touching the key.

Debian / Ubuntu

sudo apt update && sudo apt install -y \
  yubikey-manager \
  yubico-piv-tool \
  libpam-u2f \
  libfido2-1 \
  scdaemon \
  pcscd \
  opensc

Fedora / RHEL 9+ / Rocky

sudo dnf install -y \
  yubikey-manager \
  yubico-piv-tool \
  pam-u2f \
  libfido2 \
  pcsc-lite \
  opensc

Arch

sudo pacman -S --needed \
  yubikey-manager \
  yubico-piv-tool \
  pam-u2f \
  libfido2 \
  ccid \
  opensc

Enable the PC/SC daemon so smart-card modes work reliably:

sudo systemctl enable --now pcscd.socket

Add the Udev Rule

Without a udev rule, accessing the key requires root. Yubico ships an official ruleset. If your package manager did not install it automatically, add it manually.

# Check whether the rules are already present
ls /etc/udev/rules.d/ | grep -i yubi
# or
ls /usr/lib/udev/rules.d/ | grep -i yubi

If nothing appears, download and install the rules:

curl -fsSL https://raw.githubusercontent.com/Yubico/libu2f-host/master/70-u2f.rules \
  | sudo tee /etc/udev/rules.d/70-u2f.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

Re-plug the key after running this. Verify the key is detected:

ykman info

You should see device type, firmware version, and enabled interfaces. Output will vary by model.

PIV: Certificate-Based SSH and Client Auth

PIV slot 9a is the authentication slot. The steps below generate a key on the device itself — the private key never leaves the hardware.

Reset PIV (Optional, New Key)

# Default PIN is 123456, PUK is 12345678
# Change them immediately
ykman piv access change-pin
ykman piv access change-puk
ykman piv access change-management-key --generate --protect

Generate a Key Pair in Slot 9a

ykman piv keys generate \
  --algorithm ECCP384 \
  9a \
  pubkey.pem

Create a Self-Signed Certificate (or Use a CA)

ykman piv certificates generate \
  --subject "CN=YubiKey SSH" \
  9a \
  pubkey.pem

Export the SSH Public Key

ssh-keygen -D /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so -e

On Fedora/Arch the library path is /usr/lib64/pkcs11/opensc-pkcs11.so or /usr/lib/opensc-pkcs11.so. Append the output to ~/.ssh/authorized_keys on any target server.

Configure the SSH Client

# ~/.ssh/config
Host myserver
    HostName 192.0.2.10
    User alice
    PKCS11Provider /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so

When you run ssh myserver, the key taps your PIN and blinks for a touch confirmation.

FIDO2: sudo and Login via PAM

The pam_u2f module lets you authenticate to sudo, su, or a full login with a physical key press. FIDO2 is supported on YubiKey 5 series and later.

Register the Key

mkdir -p ~/.config/Yubico
pamu2fcfg >> ~/.config/Yubico/u2f_keys

Touch the key when it blinks. If you own a backup key, run pamu2fcfg -n (no first-factor) and append the second key to the same file.

Configure PAM for sudo

Test in a separate terminal before closing your current root session. Edit /etc/pam.d/sudo:

# Add ABOVE the existing @include or auth lines
# 'required' means key is mandatory; use 'sufficient' for optional
auth  required  pam_u2f.so authfile=/home/%u/.config/Yubico/u2f_keys cue

Open a new terminal and run sudo echo ok. After entering your password you will be prompted to touch the key. The cue option prints Please touch your authenticator so you know when to act.

Passwordless sudo with FIDO2 Only

Replace the sudo PAM stack with FIDO2 as the sole factor at your own risk — losing the key locks you out of sudo:

auth  sufficient  pam_u2f.so authfile=/home/%u/.config/Yubico/u2f_keys cue

OpenPGP Smart Card: GPG and SSH via gpg-agent

The YubiKey OpenPGP applet stores up to three subkeys (sign, encrypt, authenticate). The authenticate subkey works as an SSH key via gpg-agent.

Transfer GPG Subkeys to the Key

This assumes you already have a GPG master key with subkeys. Moving subkeys to hardware is destructive on the host — take a backup first.

gpg --edit-key YOUR_KEY_ID
# At the gpg> prompt:
key 1        # select signing subkey
keytocard    # choose slot 1 (Signature)
key 1        # deselect
key 2        # select encryption subkey
keytocard    # choose slot 2 (Encryption)
key 2
key 3        # select authentication subkey
keytocard    # choose slot 3 (Authentication)
save

Enable SSH Support in gpg-agent

echo 'enable-ssh-support' >> ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent   # restart to pick up changes

Point SSH at gpg-agent

Add to your shell rc (~/.bashrc or ~/.zshrc):

export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)

Source the file, then:

ssh-add -L   # should list the authentication subkey

Distribute that public key to any server you want to log into. The YubiKey PIN is your passphrase; the key never leaves the hardware.

Verify Everything Is Working

# YubiKey device info
ykman info

# List PIV certificates
ykman piv info

# List OpenPGP card status
gpg --card-status

# FIDO2 credentials on device
ykman fido list

Troubleshooting

"No YubiKey detected" from ykman

• Confirm the udev rules are in place and reload: sudo udevadm control --reload-rules && sudo udevadm trigger, then re-plug.
• Check lsusb — the key should appear as a Yubico device.
• On some Wayland compositors, flatpak-sandboxed browsers or apps may not see the device; use native packages where possible.

PIV operations fail with "Failed to connect"

• Ensure pcscd.socket is active: systemctl status pcscd.socket.
• Conflicts between pcscd and gpg-agent --card-daemon are common — only one can hold the card at a time. Kill gpg-agent (gpgconf --kill gpg-agent) before PIV operations.

PAM u2f not prompting for touch

• Verify the authfile path matches exactly — a wrong path silently falls through if you used sufficient instead of required.
• Run pamu2fcfg again and confirm the new entry appears in ~/.config/Yubico/u2f_keys.
• Check journalctl -e _COMM=sudo for PAM error messages.

SSH via gpg-agent offers wrong key

• Ensure SSH_AUTH_SOCK points to gpgconf --list-dirs agent-ssh-socket, not the default ssh-agent socket.
• If both a native ssh-agent and gpg-agent are running, the wrong one usually wins. Kill the native agent or remove it from session startup.