Using a YubiKey for SSH authentication

September 3, 2018

This is a guide for using a YubiKey for SSH authentication.

There are plenty of guides about how to do this. I find they focus too much on GPG and management of GPG keys. If you don't care about GPG except as an avenue to SSH authentication, then this guide is for you.

I've written this guide for Debian Linux. The instructions will likely work with minor tweaks for other distributions.

Steps

apt-get install gnupg pcscd scdaemon.
Plug in your YubiKey.
Run gpg --card-edit. You'll be at a GPG prompt.
Enter admin to enter admin mode.
Enter generate to generate a GPG key.
gpg will ask whether you want an off card backup of your GPG key. Say no.
gpg will ask for your admin PIN. By default this is 12345678.
gpg will ask for your regular PIN. By default this is 123456.
gpg will ask for the key's expiry date. Choose 0 for no expiry.
gpg will ask for your name, email, and a comment about the key.
After you choose okay it will take about 30 seconds to generate the key.
You'll be back at the gpg prompt. Exit.
Run echo enable-ssh-support >> ~/.gnupg/gpg-agent.conf.
Run export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket). This means we use gpg-agent instead of ssh-agent.
Get the SSH public key: ssh-add -L. You'll see something like ssh-rsa [etc].
Put the key into a host's ~/.ssh/authorized_keys file as usual.
ssh as usual.

You'll want to do this as well:

Add the export SSH_AUTH_SOCK [etc] command to your ~/.bashrc so that ssh always uses gpg-agent instead of ssh-agent.
Change the PINs on your keys. See here for an example of doing that (in the example section).

If you find gpg-agent isn't prompting you for your PIN in a nice way, you might also want to do these:

Run gpg-connect-agent updatestartuptty /bye > /dev/null so gpg-agent knows where to ask for a PIN. You may want this in your ~/.bashrc.
You may want to add aliases for ssh and scp so that you run gpg-connect-agent immediately prior to them. This helps ensure that the PIN entry dialogue goes to the correct tty.
- alias ssh="gpg-connect-agent updatestartuptty /bye > /dev/null; ssh"
- alias scp="gpg-connect-agent updatestartuptty /bye > /dev/null; scp"

Gotchas

`gpg: OpenPGP card not available: No SmartCard daemon`

Install scdaemon.

`gpg: OpenPGP card not available: No such device`

Install pcscd.

`sign_and_send_pubkey: signing failed: agent refused operation`

Run gpg-connect-agent updatestartuptty /bye.

The One and the Many