YubiKey Setup & Configuration

Configure a new YubiKey for FIDO2 SSH authentication and register public key across all infrastructure.

1. Pre-Flight Checklist

  • New YubiKey in hand (5C NFC, 5C Nano, or similar with FIDO2)

  • YubiKey Manager installed (ykman)

  • OpenSSH 8.2+ (for FIDO2 support)

  • Access to all infrastructure (to add new public key)

2. Phase 1: Identify and Initialize YubiKey

2.1. 1.1 Verify YubiKey Detection

Insert YubiKey and verify:

ykman info
Expected Output
Device type: YubiKey 5C NFC
Serial number: 12345678
Firmware version: 5.4.3
Form factor: Keychain (USB-C)
Enabled USB interfaces: OTP, FIDO, CCID
...

2.2. 1.2 Record Serial Number

SERIAL=$(ykman info | awk '/Serial number:/ {print $3}')
echo "Serial: ${SERIAL}"

Write this down - you’ll use it to identify this key.

2.3. 1.3 Reset FIDO2 (Optional - New Key Only)

This erases ALL FIDO2 credentials on the YubiKey. Only do this on a NEW key.

 
# Only if you want a fresh start
ykman fido reset

2.4. 1.4 Set FIDO2 PIN

ykman fido access change-pin

Enter a strong PIN (8+ characters recommended).

3. Phase 2: Generate SSH Key

3.1. 2.1 Determine Key Slot Name

Choose a descriptive name based on YubiKey role:

Role Key Filename

Primary (keychain)

id_ed25519_sk_rk_d000

Secondary (backup)

id_ed25519_sk_rk_d000_secondary

Tertiary (nano)

id_ed25519_sk_rk_d000_nano

Quaternary (offsite)

id_ed25519_sk_rk_d000_quaternary

New 5th key

id_ed25519_sk_rk_d000_fifth

3.2. 2.2 Generate FIDO2 Resident Key

# Replace KEY_NAME with your chosen name
KEY_NAME="id_ed25519_sk_rk_d000_quaternary"

ssh-keygen -t ed25519-sk -O resident -O verify-required \
    -C "evanusmodestus@d000-yubikey-${SERIAL}" \
    -f ~/.ssh/${KEY_NAME}

Touch YubiKey when prompted.

3.3. 2.3 Verify Key Created

ls -la ~/.ssh/${KEY_NAME}*

Should show: - ~/.ssh/id_ed25519_sk_rk_d000_quaternary (private handle) - ~/.ssh/id_ed25519_sk_rk_d000_quaternary.pub (public key)

3.4. 2.4 Extract Public Key

cat ~/.ssh/${KEY_NAME}.pub

Copy this - you’ll add it to all servers.

4. Phase 3: Add to SSH Agent

4.1. 3.1 Add Key to Agent

ssh-add -K ~/.ssh/${KEY_NAME}

Touch YubiKey when prompted.

4.2. 3.2 Verify Key Loaded

ssh-add -l | grep sk

5. Phase 4: Register on Infrastructure

5.1. 4.1 Prepare Public Key for Distribution

PUBKEY=$(cat ~/.ssh/${KEY_NAME}.pub)
echo "${PUBKEY}"

5.2. 4.2 Add to Linux Hosts

For each Linux host:

# SSH with existing key, then add new key
ssh vault-01 "echo '${PUBKEY}' >> ~/.ssh/authorized_keys"
ssh ise-01 "echo '${PUBKEY}' >> ~/.ssh/authorized_keys"
ssh keycloak-01 "echo '${PUBKEY}' >> ~/.ssh/authorized_keys"
ssh home-dc01 "echo '${PUBKEY}' >> ~/.ssh/authorized_keys"
ssh nas-01 "echo '${PUBKEY}' >> ~/.ssh/authorized_keys"
ssh bind-01 "echo '${PUBKEY}' >> ~/.ssh/authorized_keys"
ssh k3s-master-01 "echo '${PUBKEY}' >> ~/.ssh/authorized_keys"
ssh pfsense-01 "echo '${PUBKEY}' >> ~/.ssh/authorized_keys"

5.3. 4.3 Add to Network Devices

Catalyst/IOS-XE (WLC, C9300):

# Get the key in IOS format
echo "${PUBKEY}" | awk '{print $2}'

Then on device:

conf t
ip ssh pubkey-chain
  username admin
    key-string
    <paste base64 key>
    exit
  exit
exit

5.4. 4.4 Verify Addition (Sample Hosts)

# Test with new key specifically
ssh -i ~/.ssh/${KEY_NAME} vault-01 "hostname"
ssh -i ~/.ssh/${KEY_NAME} k3s-master-01 "hostname"

6. Phase 5: Update SSH Config

6.1. 5.1 Add Key to SSH Config

Edit ~/.ssh/config:

# Add this block for all hosts that should use this YubiKey
Host vault-01 ise-01 keycloak-01 home-dc01 nas-01 bind-01 k3s-master-01
    IdentityFile ~/.ssh/id_ed25519_sk_rk_d000_quaternary
    IdentityFile ~/.ssh/id_ed25519_sk_rk_d000  # fallback
    IdentitiesOnly yes

6.2. 5.2 Verify Config Syntax

ssh -G vault-01 | grep -i identityfile

7. Phase 6: Validate All Infrastructure

7.1. 6.1 Run Validation Script

# Quick validation loop
for host in vault-01 ise-01 keycloak-01 home-dc01 nas-01 bind-01 k3s-master-01 pfsense-01; do
    echo -n "${host}: "
    if timeout 5 ssh -o BatchMode=yes -i ~/.ssh/${KEY_NAME} ${host} "echo OK" 2>/dev/null; then
        echo "OK"
    else
        echo "FAILED"
    fi
done

7.2. 6.2 Update YubiKey Inventory

Update yubikey-ssh-validation.adoc with new key:

|Quaternary
|YubiKey 5C NFC (Serial: XXXXXXXX)
|Off-site
|`~/.ssh/id_ed25519_sk_rk_d000_quaternary`

8. Phase 7: Document and Backup

8.1. 7.1 Update Documentation

Add to your YubiKey hierarchy table in runbooks.

8.2. 7.2 Backup Public Key

# Copy to gopass for record
gopass insert -m v3/domains/d000/yubikey/${SERIAL}/pubkey < ~/.ssh/${KEY_NAME}.pub

8.3. 7.3 Store Physical Key

| Role | Storage Location | |------|------------------| | Primary | Keychain (daily carry) | | Secondary | Home safe/drawer | | Tertiary (Nano) | Always plugged into laptop | | Quaternary | Off-site (family, safe deposit) |

9. Quick Reference

Task Command

Check YubiKey

ykman info

Reset FIDO2

ykman fido reset

Set PIN

ykman fido access change-pin

Generate resident key

ssh-keygen -t ed25519-sk -O resident -O verify-required

Add to agent

ssh-add -K ~/.ssh/KEY

List agent keys

ssh-add -l

Test specific key

ssh -i ~/.ssh/KEY hostname

10. Troubleshooting

Issue Solution

No authenticator present

Insert YubiKey, check ykman info

Operation not permitted

udev rules. Run: sudo cp /usr/share/doc/yubikey-manager/69-yubikey.rules /etc/udev/rules.d/

PIN required

Enter FIDO2 PIN when prompted

Key not found on host

Check authorized_keys: ssh host "cat ~/.ssh/authorized_keys | grep sk"

Timeout on touch

Touch YubiKey when blinking

11. Related