Runbook: YubiKey SSH Validation

Last Updated

2026-01-24

Owner

evanusmodestus

Frequency

Monthly / After key changes

Purpose

Validate that BOTH primary and backup YubiKeys can authenticate to all critical infrastructure via SSH. This ensures disaster recovery capability if one key is lost or damaged.

Prerequisites

  • Primary YubiKey

  • Backup YubiKey

  • SSH config with proper IdentityFile entries

Key Files

Key Path

Primary

~/.ssh/id_ed25519_sk_rk_d000

Backup

~/.ssh/id_ed25519_sk_rk_d000_secondary

Software fallback

~/.ssh/id_ed25519_d000

Hosts to Validate

  • certmgr-01 (10.50.1.60)

  • ipsk-manager

  • kvm-host

  • Synology NAS (nas-01)

  • pfSense (if SSH enabled)

Procedure

Step 1: Test Primary YubiKey

Insert primary YubiKey and test each host:

# certmgr-01
ssh certmgr-01 "hostname && echo 'PRIMARY KEY OK'"

# ipsk-manager
ssh ipsk-manager "hostname && echo 'PRIMARY KEY OK'"

# kvm-host
ssh kvm-host "hostname && echo 'PRIMARY KEY OK'"

# nas-01 (Synology)
ssh nas-01 "hostname && echo 'PRIMARY KEY OK'"

Touch YubiKey when prompted.

Step 2: Test Backup YubiKey

Remove primary YubiKey, insert backup YubiKey, and repeat:

# certmgr-01
ssh certmgr-01 "hostname && echo 'BACKUP KEY OK'"

# ipsk-manager
ssh ipsk-manager "hostname && echo 'BACKUP KEY OK'"

# kvm-host
ssh kvm-host "hostname && echo 'BACKUP KEY OK'"

# nas-01 (Synology)
ssh nas-01 "hostname && echo 'BACKUP KEY OK'"

Step 3: Test Software Fallback (Optional)

If software key should work as fallback:

# Remove all YubiKeys
ssh -i ~/.ssh/id_ed25519_d000 certmgr-01 "hostname && echo 'SOFTWARE KEY OK'"

Verification Checklist

  • Primary YubiKey works on all hosts

  • Backup YubiKey works on all hosts

  • Software key works (if applicable)

  • No hosts failed authentication

Troubleshooting

Permission Denied

Symptom: Permission denied (publickey)

Cause: Public key not in authorized_keys

Resolution:

# Get public key from YubiKey
ssh-keygen -K  # Export resident keys

# Or manually add to remote host
cat ~/.ssh/id_ed25519_sk_rk_d000.pub
# Add this to remote ~/.ssh/authorized_keys

YubiKey Not Detected

Symptom: No such device or key not found

Cause: YubiKey not properly connected or FIDO2 not enabled

Resolution:

# Check if YubiKey detected
ykman info

# List FIDO2 credentials
ykman fido credentials list

Wrong Key Used

Symptom: SSH tries wrong key file

Resolution:

Check ~/.ssh/config has correct IdentityFile order:

Host certmgr-01
    HostName 10.50.1.60
    User ansible
    IdentityFile ~/.ssh/id_ed25519_sk_rk_d000
    IdentityFile ~/.ssh/id_ed25519_sk_rk_d000_secondary
    IdentityFile ~/.ssh/id_ed25519_d000

Recovery: Adding Key to New Host

If a host is missing the public key:

# From workstation with working key
ssh-copy-id -i ~/.ssh/id_ed25519_sk_rk_d000.pub user@newhost

Notes

*