#pkcs11

yubico-piv-tool 1.4.0, Mac OS X 10.11.5

While you should generate your ssh keys on card or generate them on a sterile machine for escrow, you can also import an existing ssh key (usually found in ~/.ssh/id_rsa). Below is a walkthrough on how to do that. Be sure to import both the private and public side of your keypair; otherwise, ssh auth might not work. You should probably create an encrypted disk and chdir to that disk when changing the private key to pem form.

Private Key

rchapman@Macbook:~$ cd /Volumes/encrypted/ rchapman@Macbook:/Volumes/encrypted$ openssl rsa -in ~/.ssh/id_rsa -out id_rsa.pem -outform pem Enter pass phrase for /Users/rchapman/.ssh/id_rsa: writing RSA key rchapman@Macbook:/Volumes/encrypted$ head -1 id_rsa.pem -----BEGIN RSA PRIVATE KEY----- rchapman@Macbook:/Volumes/encrypted$ yubico-piv-tool -a import-key -s 9a -i id_rsa.pem Successfully imported a new private key. rchapman@Macbook:/Volumes/encrypted$ rm id_rsa.pem

Public Key

rchapman@Macbook:/Volumes/encrypted$ ssh-keygen -e -f ~/.ssh/id_rsa.pub -m PKCS8 > id_rsa.pub.pkcs8 rchapman@Macbook:/Volumes/encrypted$ head -1 id_rsa.pub.pkcs8 -----BEGIN PUBLIC KEY----- rchapman@Macbook:/Volumes/encrypted$ ~/bin/yubico-piv-tool -a verify -P 123456 -a selfsign-certificate -s 9a -S "/CN=joe/O=Test/" -i id_rsa.pub.pkcs8 -o 9a-cert.pem rchapman@Macbook:/Volumes/encrypted$ ~/bin/yubico-piv-tool -a verify -P 123456 -a import-certificate -s 9a -i 9a-cert.pem ; ~/bin/yubico-piv-tool -a status Successfully verified PIN. Successfully imported a new certificate. CHUID: 3019...fe00 CCC: f015...fe00 Slot 9a: Algorithm: RSA2048 Subject DN: CN=joe, O=Test Issuer DN: CN=joe, O=Test Fingerprint: cf...46 Not Before: Jun 20 19:13:41 2016 GMT Not After: Jun 20 19:13:41 2017 GMT [...] PIN tries left: 15

Move .ssh/id_rsa and restart ssh-agent (otherwise it will be cached by the agent)

rchapman@Macbook:/Volumes/encrypted$ cd ~/.ssh rchapman@Macbook:~/.ssh$ mv id_rsa .. rchapman@Macbook:~/.ssh$ pkill ssh-agent rchapman@Macbook:~/.ssh$ sudo launchctl start org.openbsd.ssh-agent

Set PIN and PIN Retries

You should change the user PIN as well as the PIN Unlock Code (PUK) if you have not already. The YubiKey NEO asks for the PIN every time it signs a nonce (to log you into a ssh server). If you enter the PIN wrong a number of times (3 by default), then the PIN will be locked. You can then use the PUK to unlock the PIN. If you enter the PUK wrong a number of times (again, 3 by default), then the PIV applet will bulk erase it's memory, causing your private keys and certificates to be lost. At that point, you have to reset the PIV applet and re-populate the certs and private keys.

To change the PIN and PUK retries from 3 to 15:

rchapman@Macbook:~$ unset HISTFILE rchapman@Macbook:~$ ~/bin/yubico-piv-tool -a verify -P 123456 -a pin-retries --pin-retries 15 --puk-retries 15

Note that this step will also set the PIN and PUK codes back to factory default, so you'll need to change your PIN/PUK codes after doing this step if you already had PIN/PUK codes set.

To change the PIN and PUK: In this example, we are changing the PIN from the default value of 123456 to 987600 and the PUK from the default of 12345678 to 98761234

rchapman@Macbook:~$ ~/bin/yubico-piv-tool -a change-pin --pin 123456 --new-pin=987600 rchapman@Macbook:~$ ~/bin/yubico-piv-tool -a change-puk --pin 12345678 --new-pin=98761234

Change the management key Most security professionals would say you should change the management key as well. This is a 24 byte key which resides in slot 9B. If you forget it, you can still reset the PIV applet, which will reset the PIN, PUK, and 9B key back to defaults.

rchapman@Macbook:~$ ~/bin/yubico-piv-tool -a set-mgm-key -n 123456789012345678901234567890123456789012345678

Logout and log back in, then make sure the PIN, PUK and management key are not in ~/.bash_history

Key Escrow

If you want to encrypt the private key for storage in escrow:

rchapman@Macbook:~$ cat ~/id_rsa | gpg --symmetric | base64

One place where you could store the encrypted base-64 encoded private key would be the password field of a password manager like 1Password. To decrypt it later:

echo "base64string" | base64 -D | gpg --decrypt

Last steps

Later, when you are sure you are happy with the encrypted version of the file, remove your private key from your workstation (after all, the reason for putting your private key on a hardware token is to prevent someone from stealing it off disk).