Yubikey as an SSH key
As of 2020-05-09 Filippo Valsorda has released yubikey-agent. I am now recommending this method over using PKCS#11, however if you still wish to use the native ssh-agent, read on.
All other guides I've seen (https://github.com/drduh/YubiKey-Guide being the most prolific) tell you to use the Yubikey's smartcard (PKCS#11) features with GnuPG via gpg-agent.
STOP THE MADNESS!
OpenSSH has supported OpenSC since version 5.4. This means that all you need to do is install the OpenSC library and tell SSH to use that library as your identity.
Prequisites
1. Install OpenSC and YubiKey Manager (CLI only)
On macOS
Ensure you install the cask version of OpenSC, not the formula. The cask version is a .pkg which will install the shared library to a location acceptable by ssh-agent. The formula does not, as Homebrew installs each version into its own location and it won't allow an unknown path to be used as a PKCS#11 library.
brew install --cask opensc
brew install ykman On Ubuntu/Debian
sudo apt-add-repository ppa:yubico/stable
sudo apt update
sudo apt install opensc yubikey-manager
2. If this is a new Yubikey, change the default PIV management key, PIN and PUK.
The ykman tool can generate a new management key for you. For the PIN and PUK you'll need to provide your own values (6-8 digits).
ykman piv change-management-key --touch --generate
ykman piv change-pin -P 123456
ykman piv change-puk -p 12345678
Make sure you save the generated password somewhere secure such as a password manager. The management key is needed any time you generate a keypair, import a certificate or change the number of PIN or PUK retries
The PUK should also be kept somewhere safe. This is used if the PIN is entered incorrectly too many times.
How?
I did this all on macOS 10.14. Linux distributions should work in a similar way. This is based on Yubico's instructions but uses the newer ykman utility instead of the older yubico-piv-tool. The older tool doesn't seem to support generating PIV certificates and gives misleading errors.
- Ensure CCID mode is enabled on the Yubikey
ykman mode
If CCID is not in the list, enable it by adding CCID to the list, e.g.
ykman mode OTP+FIDO+CCID
(This assumes you had OTP+FIDO previously, and still want them enabled.)
- Generate a PIV key and output the public key
ykman piv generate-key 9a pubkey.pem
Alternatively, you can require that you have to touch the Yubikey every time the slot is accessed:
ykman piv generate-key --touch-policy always 9a pubkey.pem
This is an RSA 2048-bit key by default. Depending which Yubikey you have, you can change it using -a / --algorithm.
(9a is the PIV authentication slot.)
- Generate a self-signed X.509 certificate
ykman piv generate-certificate -s "SSH key" 9a pubkey.pem
- Export your SSH public key from the Yubikey
ssh-keygen -D /usr/local/lib/opensc-pkcs11.so
And that's all the hard stuff done.
Now just add the public key to your authorized_keys file on a remote host and try to use it:
ssh -I /usr/local/lib/opensc-pkcs11.so -i /usr/local/lib/opensc-pkcs11.so -o IdentitiesOnly=yes server.example.com
You should be prompted for your Yubikey's PIV PIN.
You can add the PKCS11 library to ssh-agent.
ssh-add -s /usr/local/lib/opensc-pkcs11.so
Once more you will be prompted for your PIN, and from there SSH authentication will happen as usual.
To configure ssh to use the Yubikey's SSH key, use the PKCS11Provider config option instead of IdentityFile, e.g.:
Host foo
PKCS11Provider /usr/local/lib/opensc-pkcs11.so
IdentitiesOnly yes
Additional notes
-
When SSHing, you may get prompted with the key's subject name, like
Enter PIN for 'SSH key':. But if you add the key to the agent, you'll get a prompt likeEnter passphrase for PKCS#11:. These are the same PIN (your PIV PIN). -
If you remove the key from ssh-agent using
ssh-add -dorssh-add -D, you'll have to either remove and re-add the PKCS library to the agent or restart the agent.- To re-add the library run
ssh-add -e /usr/local/lib/opensc-pkcs11.so ssh-add -s /usr/local/lib/opensc-pkcs11.so - On macOS, you can restart the agent with
launchctl stop com.openssh.ssh-agent launchctl start com.openssh.ssh-agent
- To re-add the library run