Yubikey Cheatsheet

I believe the Yubikey (From Yubico) is probably the best solution (for now) that you can have if you wish to ditch using strong unique passwords for everything. Essentially it is just a clever smart card that you can plug into your computer, that can be used for private cryptographic keys of various types, but I like to think of it as a physical key to the digital world. Just as you use a key to open your front door, you should use this key to gain access to your servers over SSH. I believe it is definitely safer than using a service like LastPass which I see a lot of people using. You just need to remember to take it with you, and don't lose it!

Related Material

• Enable Yubikey For Gmail 2-factor authentication.
• Enable FIDO in Firefox.

Cheats

Geting API Key

Go here to get your Yubikey API key. You don't need this if you wish to log into remote servers using a PIN to unlock your SSH private key, but you will need it if you wish to use the button to authenticate instead of the PIN (e.g. using one-time-passwords OTP)

Install Card Reader Software (Client)

Install the open smart card reader which will allow us to talk to our yubikey. You only need this on your local computer's that you will plug the yubikey into (e.g. not your servers).

sudo apt install opensc -y

Install the Yubico-piv-tool (Client)

Your local client computer will need this tool for interacting with your yubikey. You do not need this on servers you wish to connect to via SSH.

Ubuntu users should use the repository:

sudo apt-add-repository ppa:yubico/stable -y
sudo apt update
sudo apt install yubico-piv-tool -y

Install Libpam Yubico (Servers)

If you wish to connect to your servers via SSH using the one time password (OTP) functionality of your Yubikey, you will need to install this on your servers. However, if you are happy to connect to the servers using your Yubikey and remembering its security PIN, you do not need this.

Ubuntu Servers:

sudo add-apt-repository ppa:yubico/stable -y
sudo apt-get update
sudo apt-get install libpam-yubico -y

Debian Servers:

sudo apt-get install libpam-yubico

CentOS/Fedora/Arch (EPEL repository)

sudo yum install pam_yubico

Verify Your Pin

Use this command to check that the PIN on the Yubikey is what you think it is.

yubico-piv-tool --action verify-pin -P xxxxxx

Change The Pin

yubico-piv-tool \
  --action change-pin \
  --pin $OLD_PIN \
  --new-pin $NEW_PIN

The default pin on they yubikeys is 123456 and 12345678 for the PUC.

Generate Public RSA Certificate

yubico-piv-tool \
  --slot 9a \
  --action generate \
  -o public.pem

Get Status

yubico-piv-tool --action status

Example output

CHUID:  No data available
CCC:    No data available
Slot 9a:    
    Algorithm:  RSA2048
    Subject DN: CN=Programster's SSH Key
    Issuer DN:  CN=Programster's SSH Key
    Fingerprint:    67c82d402cf1d738a5d4b3d2dc6e374b6987aac17d41963e396b9ef62a9647d4
    Not Before: May 13 10:36:33 2018 GMT
    Not After:  May 13 10:36:33 2019 GMT
PIN tries left: 3

Generate Self-Signed RSA Certificate

After you have generated a public certificate, you can use that certificate in this command to generate the corresponding self-signed private certificate.

PIN=123456
CERT_CANONICAL_NAME="Programster's SSH Key"
PUBLIC_KEY_FILE="public.pem"
OUTPUT_FILENAME="private.pem"

yubico-piv-tool \
  --action verify-pin -P $PIN \
  --action selfsign-certificate \
  --slot 9a \
  --subject "/CN=$CERT_CANONICAL_NAME/" \
  --input $PUBLIC_KEY_FILE \
  --output $OUTPUT_FILENAME

Import RSA Certificate

Use this command to import your private, self-signed certificate.

yubico-piv-tool \
  --action import-certificate \
  --slot 9a \
  --input private.pem

Extract Public SSH Key

This will extract the necessary SSH public key from the Yubikey that you should use on your remote hosts if you want to be able to use the Yubikey to sign into them.

ssh-keygen \
  -D /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so \
  > my-ssh-public-key.pub

You will need to append the contents of this file to the $HOME/.ssh/authorized_keys file of the servers that you want to be able to log into by using the Yubikey.

If you want to make this your default public key copy the file to $HOME/.ssh/id_rsa.pub. Doing so will allow you to use the following command to copy the public key over to the remote servers, without having to perform any of that manual editing of the authorized_keys file.

ssh-copy-id -f user@hostname

We have to use -f because the tool will notice that we don't have the corresponding private key file. This is okay because it is on the Yubikey.

Configure Client Computer To Use Yubikey For SSH

Run the following command to configure your local computer to look at the Yubikey when trying to get the private key for SSH authentication.

sudo echo "PKCS11Provider /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so" \
| sudo tee -a /etc/ssh/ssh_config

Configure Server To Use Yubikey PAM

After having installed the libpam yubico software on the server (see above):

Create the file for authorized yubikey users.

sudo editor /etc/ssh/authorized_yubikeys

Fill it with the username followed by a colon and the first 12 characters of the OTP of the yubikey. If the user has multiple keys, just keep adding them separated by colons. E.g.

programster:abcdefghijkl
user-with-multiple-yubikeys:abcdefghijkl:123456789abc

Now we are going to edit our /etc/pam.d/sshd configuration file to tell it to use that file we just created for authentication, and to tell it that using the Yuikey OTP is enough on its own for authentication.

REQUIRED_OR_SUFFICIENT="sufficient"
CLIENT_ID=37979
SECRET_KEY=xtXLE9VWrKam9Te62/Q75qgtJ78=

# We need to add this line to the TOP of the file otherwise will always be prompted for password
LINE="auth $REQUIRED_OR_SUFFICIENT pam_yubico.so id=$CLIENT_ID key=$SECRET_KEY authfile=/etc/ssh/authorized_yubikeys"
FILE="/etc/pam.d/sshd"
sudo sed -i "1s|^|$LINE \n|"  $FILE

The CLIENT_ID and SECRET_KEY are provided to you by Yubikey when you got the API key. Change sufficient to required if you wish to use your Yubikey as a 2-factor device rather than use it on its own for authorization on its own (e.g. if you still want to have to enter a password).

Now edit your servers SSH configuration file to tell it to use PAM which we just configured.

sudo editor /etc/ssh/sshd_config

Ensure the following configurations are set:

ChallengeResponseAuthentication yes
UsePAM yes

Restart the SSH service.

sudo systemctl restart sshd

Debugging

SSH No Identity

If you get the following message when trying to connect to a remote server using the yubikey...

no such identity: /home/stuart/.ssh/id_ed25519: No such file or directory

This is probably because you haven't copied the public SSH key over to the server yet.

General Information

What is PIV?

Personal Identity Verification

Slots

There are four PIV slots on the YubiKey. Each slot is reserved for a specific purpose as defined by the NIST specifications:

• 9a - PIV Authentication
• 9c - Digtial Signature
• 9d - Key Management
• 9e - Card Authentication

3 Pins

The Yubikey has 3 pins.

The first is the 8-digit admin PIN is used for certain operations. It's important to change this because it is used in order to change your second pin.

The second pin is a 6-digit user PIN which you use on a day-to-day basis to use your GPG key to sign or encrypt.

The third PIN is the Reset PIN which can be used to reset your YubiKey to the original factory settings. This will also trash your GPG key. If your YubiKey got stolen, the thief wouldn't get access to your GPG key so it's not so critical to change this.

References

• Yubico PIV Tool Command Line Guide
• Youtube - Linux Action Show #373 - SSH Authentication with YubiKey
• Linode - How to use a YubiKey for Two-Factor Secure Shell Authentication