SSH Resident Keys

Using SSH Resident Keys (FIDO2)

• YubiKey hardware token initialized with a PIN (most people set this up first).
• A YubiKey FIDO2-compatible hardware token
• OpenSSH 8.2+ (supports ed25519-sk keys).
• ssh-keygen on Linux/macOS/Windows with WSL.

On macos you will need to install openssh and ykman. You will also need to install libfido2 for FIDO2 support. Without the libfido2 package, you will not be able to use ssh-keygen -K to list/extract resident keys.

brew install openssh ykman libfido2

list passkeys and resident keys on yubikey (max 25 slots available)

ykman fido credentials list

delete ssh resident keys on yubikey

ykman fido credentials list
ykman fido credentials delete <Credential ID>

list ssh keys on ssh-agent

ssh-add -l

Decide on your threat model

# No PIN or touch are required
ssh-keygen -t ed25519-sk -O resident -O no-touch-required
# PIN but no touch required
ssh-keygen -t ed25519-sk -O resident -O verify-required -O no-touch-required
# No PIN but touch is required
ssh-keygen -t ed25519-sk -O resident
# A PIN and a touch are required (most secure)
ssh-keygen -t ed25519-sk -O resident -O verify-required

(Optional) -O application=ssh:<identifier> when creating multiple keys

# no passphrase needed (PIN used instead)
ssh-keygen -t ed25519-sk -O resident -O verify-required -O application=ssh:dohjon -C "yubikey-cat"
# see .ssh dir

Ensure ssh-agent is started

ps aux | grep ssh-agent
# eval "$(ssh-agent -s)"

Add keys temporarily to ssh-agent

ssh-add -l
ssh-add -K
ssh-add -l

Insert yubikey and cd to .ssh directory then run command to add resident ssh keys to new computer

cd ~/.ssh
ssh-keygen -K

Test connection to github

ssh -T [email protected]
# ssh -T -i ~/.ssh/id_ed25519_sk_rk_dohjon [email protected]

Tell GitHub to Use This SSH Key (Optional) If you have multiple SSH keys and want to make sure GitHub uses this specific one, you can configure it in your ~/.ssh/config.

Example ~/.ssh/config:

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_sk_rk_dohjon
    IdentitiesOnly yes

Note!

id_ed25519_sk: means it's an SSH key (sk = security key) using the Ed25519 algorithm. rk: it's a resident key, stored in the hardware token. When using -O application=ssh:<identifier> it also adds the identifier last

id*ed25519_sk_rk_<identifier>

You need the public key (.pub file) in the ~/.ssh/authorized_keys file on any server you're trying to access.

ssh-copy-id -i ~/.ssh/id_ed25519_sk_rk_<something>.pub user@remote_host
# can be added manually as well
# cat ~/.ssh/id*ed25519_sk_rk*<something>.pub >>.ssh/authorized_keys