Table of Contents

Yubikey-based SSH Keys

By Colin on 2022-09-15

This short guide is a supplement to those supplied on the Yubico website and Arch Wiki for establishing Yubikey-based SSH keys. Doing so allows you to leave the private key(s) on the Yubikey itself, leaving no other copies around on your local machine.

These instructions should work for any systemd-based system. They diverge slightly from the official instructions from Yubico due to those being slightly out of date. The method presented here is simpler overall.


Install yubikey-manager to get the ykman executable. On an Arch system:

sudo pacman -S yubikey-manager

We also need a certain AUR package, yubico-piv-tool. Get this with a tool like Aura:

aura -A yubico-piv-tool

This gives us access to a first-class PKCS11 module from Yubico (i.e. opensc is no longer necessary).

Next allow card-like devices to be read:

sudo systemctl enable --now pcscd.socket

Now we're ready to begin.

Key Generation

We're going to start from a blank slate. Let's reset the Yubikey (at least, the parts we care about):

ykman piv reset

Now we'll set custom PINs and keys. The default PIN is 123456.

ykman piv access change-pin
ykman piv access change-puk
ykman piv access change-management-key --generate --protect

Now we'll generate our key:

ykman piv keys generate 9a public.pem
ykman piv certificates generate --subject "CN=SSH-key" 9a public.pem

The private key is now stored on the Yubikey. A public.pem file was output as well, but this is in the wrong format for SSH. Let's fix that:

ssh-keygen -D /usr/lib/ -e

This should output two SSH public keys. The one we want should be the first one. Copy this to Github (or whereever). Now add the following to the top of your /home/YOU/.ssh/config file:

PKCS11Provider /usr/lib/

To test it all:

ssh -T

You should be prompted for the PIN you set at a previous step, after which a connection is made and Github accepts the key usage. That's it! Feel free to delete the public.pem, it's no longer needed.


Blog Archive