Yubikey

Yubikey

File:YubiKey-4-keychain-and-nano.png

YubiKey 4 - hardware root of trust

YubiKey is a hardware security key that provides phishing-resistant authentication. Essential for protecting high-value accounts against credential theft.

Why Hardware Keys

Passwords can be phished. SMS codes can be intercepted. TOTP apps can be cloned. Hardware keys cannot be remotely stolen - an attacker needs physical possession.

Method	Phishing Resistant	Remote Theft	Usability
Password only	No	Yes	Easy
SMS 2FA	No	Yes (SIM swap)	Easy
TOTP (Authenticator)	No	Possible (malware)	Medium
Hardware Key	Yes	No	Easy

Which YubiKey

Recommended: YubiKey 5 NFC ($50)

• USB-A + NFC for phone tap
• Supports FIDO2, PIV, OpenPGP, OTP

For USB-C only: YubiKey 5C NFC ($55)

Budget option: Security Key NFC ($25)

• FIDO2 only (no PIV/OpenPGP)
• Still excellent for most users

Always buy two. Register both everywhere. Keep backup in secure location.

Initial Setup

Install YubiKey Manager

# macOS
brew install ykman

# Debian/Ubuntu
sudo apt install yubikey-manager

# Verify key is detected
ykman info

Set PIN

# Set FIDO2 PIN (required for passwordless)
ykman fido access change-pin

# Set PIV PIN (for certificates)
ykman piv access change-pin

Default PINs: FIDO2 has none, PIV default is 123456

FIDO2/WebAuthn Setup

Modern passwordless authentication. Register your key with supported services:

Google/Gmail

1. Security → 2-Step Verification → Security Keys
2. Add Security Key → USB/NFC
3. Insert key and tap when prompted
4. Register backup key immediately

GitHub

1. Settings → Password and authentication → Two-factor authentication
2. Security keys → Register new security key
3. Follow prompts

Microsoft/Azure

1. Security → Advanced security options → Add a new way to sign in
2. Use a security key

1Password

Settings → Security → Two-Factor Authentication → Security Keys

Other Services

Most modern services support FIDO2. Look for "Security Keys" or "Hardware Keys" in security settings.

SSH Authentication

Resident Keys (FIDO2)

Modern approach - key stored on YubiKey:

# Generate resident SSH key
ssh-keygen -t ed25519-sk -O resident -O verify-required -C "yubikey-main"

# Key is stored ON the YubiKey
# Export public key for authorized_keys
ssh-keygen -K  # Downloads from key

# Add to remote server
ssh-copy-id -i ~/.ssh/id_ed25519_sk.pub user@server

Flags explained:

• -O resident: Store key on device (not just reference)
• -O verify-required: Require PIN + touch for each use

PIV-based SSH

Traditional approach using X.509 certificates:

# Generate key in PIV slot 9a
ykman piv keys generate 9a pubkey.pem

# Create self-signed certificate
ykman piv certificates generate --subject "CN=SSH Key" 9a pubkey.pem

# Export public key for SSH
ssh-keygen -D /usr/local/lib/libykcs11.dylib -e > yubikey.pub

# Use with ssh
ssh -I /usr/local/lib/libykcs11.dylib user@server

GPG Integration

Use YubiKey as a smartcard for PGP operations:

Move Keys to Card

# Edit your key
gpg --edit-key YOUR_KEY_ID

# For each subkey, move to card
gpg> key 1
gpg> keytocard
# Select appropriate slot (signature, encryption, or authentication)
gpg> save

Slots

• Signature (1): For signing
• Encryption (2): For decryption
• Authentication (3): For SSH auth via GPG

Configure GPG Agent for SSH

Add to ~/.gnupg/gpg-agent.conf:

enable-ssh-support
pinentry-program /usr/bin/pinentry-mac  # or appropriate for your OS

Add to shell profile:

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

TOTP Backup

YubiKey can store TOTP seeds (like Google Authenticator):

# Add TOTP account (using Yubico Authenticator app)
# Or via CLI:
ykman oath accounts add -t "Service Name" SEED_SECRET

# Generate code
ykman oath accounts code "Service Name"

Note: YubiKey 5 stores up to 32 TOTP accounts. Requires touch for each code.

Static Passwords

For services that don't support 2FA, store a complex password:

# Configure slot 2 for static password
ykman otp static --keyboard-layout US 2

# Long-press generates the password

Use sparingly - this is a fallback, not primary security.

Backup Strategy

Critical: Always have a backup authentication method.

1. Two YubiKeys: Register both everywhere
2. Backup codes: Store encrypted/offline
3. Recovery email: Separate, secured account
4. Document everything: Which key is registered where

Recovery Procedure

If primary key is lost:

1. Use backup key to access accounts
2. Revoke lost key from all services
3. Order replacement
4. Register replacement as new backup

Troubleshooting

Key Not Detected

# Check USB connection
ykman info

# Reset USB stack (macOS)
sudo launchctl stop com.apple.usbd; sudo launchctl start com.apple.usbd

# Check permissions (Linux)
# Add udev rules: /etc/udev/rules.d/70-yubikey.rules

Wrong PIN Too Many Times

# FIDO2 locks after 8 attempts - must reset
ykman fido reset  # WARNING: Destroys all FIDO credentials

# PIV locks after 3 attempts
# Use PUK to unblock, or reset PIV application

NFC Not Working

• Remove phone case
• Move slowly across NFC area
• Some phones have NFC at top, some at center

Security Considerations

Physical Security: Anyone with your key AND PIN can authenticate as you.

Travel: Consider leaving backup key at home. Some border crossings may require unlocking devices.

Touch Requirement: Enable touch for operations - prevents malware from silently using key.

Firmware: Cannot be updated. Old keys may lack features but remain secure for their supported protocols.

Related

• PGP - Encrypted communications
• Threat Modeling - Security planning
• SSH - Secure remote access
• Digital Security Incident Runbook - When things go wrong

References

• Yubico WebAuthn Documentation
• drduh's YubiKey Guide - Comprehensive GPG setup