Use when setting up, troubleshooting, or hardening SSH keys for GitHub — FIDO2/U2F hardware keys (ed25519-sk/ecdsa-sk), macOS Keychain integration (UseKeychain, --apple-use-keychain), Windows MSYS2-vs-native-OpenSSH agent confusion, "Bad configuration option: usekeychain" errors, or choosing between ed25519 and rsa-4096
Prefer Ed25519. GitHub dropped DSA on 2022-03-15; RSA keys created after 2021-11-02 must sign with SHA-2 (rsa-sha2-256 / rsa-sha2-512). Fall back to RSA-4096 only when the target genuinely cannot handle Ed25519.
| Key type | When |
|---|---|
ed25519 | default; all modern systems |
rsa -b 4096 | legacy servers without Ed25519 |
ed25519-sk | FIDO2/U2F hardware key |
ecdsa-sk | hardware key whose firmware lacks Ed25519 |
The _sk file on disk is a handle, not the key. Physical device lost = key lost.
ssh-keygen -t ed25519 -C "[email protected]"
ssh-keygen -t ed25519-sk -C "[email protected]" # hardware
ssh-keygen -t ed25519-sk -O resident # store handle on device
ssh-keygen -t ed25519-sk -O verify-required # require PIN/biometric per use
ssh-keygen -t ed25519-sk -O no-touch-required # skip touch (not recommended)
Import resident keys onto a new host: ssh-add -K (lowercase K on OpenSSH 8.2+; not the macOS -K).
~/.ssh/config:
Host github.com
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_ed25519
ssh-add --apple-use-keychain ~/.ssh/id_ed25519 # Monterey+
ssh-add -K ~/.ssh/id_ed25519 # pre-Monterey
Omit UseKeychain when the key has no passphrase. If a Homebrew/MacPorts ssh-add is first on PATH, --apple-use-keychain breaks — call /usr/bin/ssh-add explicitly, and add IgnoreUnknown UseKeychain to ~/.ssh/config so non-Apple clients don't error on the directive.
Get-Service ssh-agent | Set-Service -StartupType Manual # elevated, once
Start-Service ssh-agent # elevated
ssh-add C:\Users\you\.ssh\id_ed25519 # unelevated
Git for Windows bundles its own MSYS2 OpenSSH with a separate agent. If ssh-add saved the key but git push still prompts, pin git to the system client:
git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"
ForwardAgent yes) exposes every loaded key to the remote host; root there can use them. Prefer ProxyJump or a per-host key.IdentitiesOnly yes the agent tries every key against every server, disclosing public-key fingerprints.-sk keys are device-bound: reprovision the hardware token and the public key is irrecoverable — back it up first.ssh -vT [email protected] prints which binary runs.openssh on macOS PATH: ssh-add --apple-use-keychain errors with "unknown option" — use /usr/bin/ssh-add.ssh-rsa client negotiating SHA-1 signatures will fail authentication.