Skip to content

Yubikey-PIV-as-SSH-Key

Intro

Use Yubikey as SSH Key.

Prequisites

1. Install OpenSC and YubiKey Manager (CLI only)

On Ubuntu/Debian

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.

Generate PIV Key

  1. 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.)

  1. 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.)

  1. Generate a self-signed X.509 certificate
ykman piv generate-certificate -s "SSH key" 9a pubkey.pem

Windows

  1. Setting the system path

Go to Control Panel → System and Security → System → Advanced system setting

Click “Environment Variables…“

Under System Variables, highlight “Path“ and click “Edit…“

Click “New“ and add the absolute path to Yubico PIV Tool\bin

  1. Set ssh config file

Open PowerShell and run the following:

New-Item -Path $env:USERPROFILE\.ssh\ -Name "config" -ItemType "file" -Value `
  'PKCS11Provider "C:\Program Files\Yubico\Yubico PIV Tool\bin\libykcs11.dll"'

Linux

  1. 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 like Enter passphrase for PKCS#11:. These are the same PIN (your PIV PIN).

  • If you remove the key from ssh-agent using ssh-add -d or ssh-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

REF

[1].https://github.com/jamesog/yubikey-ssh