Setting up a YubiKey for SSH / by Andrew Wyllie

Overview

A Yubikey is a small hardware device that you install in USB port on your system. Its main use is to provide multifactor authentication (MFA) when connecting to various websites that support it. So instead of having the site text/email you a six digit code and then typing that code into a form on the site, you can just touch the sensor on the yubikey to send a MFA code - much simpler. As MFA is implemented by more and more sites, this can be a very handy device. One nice side benefit is that the key can be removed from your laptop, so in theory, even if someone has access to your laptop and your passwords, without the key they will not be able to get into sites that you have configured . Yubikey is supported on many major sites. The main ones I used it on are GitHub and AWS.

Yubikeys have a number of other uses as well. One is that you can build and install your private ssh keys on it. This can be handy when configuring EC2s on AWS as well as making it easier to connect to systems on your local network. This is a quick walk through on how I created a private ssh key on my yubikey. For extra security, a PIN is required when connecting to a remote system..

RSA Key Setup for SSH

These instructions are to get an RSA key configured on your yubikey on MacOsX or Linux (not tested) for use with ssh. This is a summary of the very long and detailed version of these instructions which exist here https://github.com/drduh/YubiKey-Guide#ssh

NOTE: You'll probably want to read through all of these instructions before actually starting this process. There are a few places where you’ll need to figure out how things are setup on your own system, these instructions work for me - your milage may vary.

Step One: Install Gnu PGP (gpg) and other required software

On MacOsX, use: 

wyllie@dilex:~ $ brew install gnupg yubikey-personalization hopenpgp-tools ykman pinentry-mac




  
 On linux:


























 wyllie@dilex:~ $ sudo apt-get install -y \
     curl gnupg2 gnupg-agent cryptsetup scdaemon pcscd \ 
     yubikey-personalization dirmngr secure-delete





  
Step Two: Create a Master Key  
Use the guide referenced above to create the keys and load them on your yubikey 
Step Three: Configure the Key 
The key has two PINs on it - the regular on and the admin one. VERY IMPORTANT NOTE! If you type the admin password in incorrectly 3 times, it will lock up the key and it will need to be completely reset to factory defaults. You really want to avoid doing this! 
The default PIN for regular use is 123456 and the default admin PIN is 12345678. These obviously need to be set to something else: 


























wyllie@dilex:~ $ gpg --change-pin
gpg: OpenPGP card no. D3150201130101010009132380300000 detected
1 - change PIN
2 - unblock PIN
3 - change Admin PIN 4 - set the Reset Code Q - quit
// Enter '1' to change the PIN
Your selection? 1
// Enter the default (123456) or current PIN then enter the desired PIN twice
PIN changed.
1 - change PIN
2 - unblock PIN
3 - change Admin PIN 4 - set the Reset Code Q - quit
// Enter '3' to change the admin PIN
Your selection? 3
// Enter the default (12345678) or current PIN then enter the desired PIN twice
PIN changed.
1 - change PIN
2 - unblock PIN
3 - change Admin PIN 4 - set the Reset Code Q - quit
Your selection? q





  
 Step Four: Setup gpg-agent 
In this step, we will disable ssh-agent and install gpg-agent to replace it. The ssh private key is stored on the yubikey. When you use ssh, gpg-agent will ask for the PIN before it offers your public key to the remote machine. This will also work when using github - so a 'git push' will ask for the PIN before it honors the request. 
Create the following file in ~/.gnupg/gpg.conf  


























personal-cipher-preferences AES256 AES192 AES CAST5 
personal-digest-preferences SHA512 SHA384 SHA256 SHA224
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
cert-digest-algo SHA512
s2k-digest-algo SHA512
s2k-cipher-algo AES256
charset utf-8
fixed-list-mode
no-comments
no-emit-version
keyid-format 0xlong 
list-options show-uid-validity 
verify-options show-uid-validity 
with-fingerprint 
require-cross-certification 
use-agent




  
Create the following file in ~/.gnupg/gpg-agent .   On a mac you will use pinentry-mac for the pinentry program.  There are a few different versions to chose from on Linux.  Here some more info from the GnuPG.org


























enable-ssh-support
pinentry-program /usr/local/bin/pinentry-mac
default-cache-ttl 60
max-cache-ttl 120




  
 The following config needs to be in your .bashrc or .bash_profile


























export GPG_TTY="$(tty)"
unset SSH_AGENT_PID
export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket) gpgconf --launch gpg-agent
# Alternate config
# export GPG_TTY="$(tty)"
# export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh" # gpg-connect-agent updatestartuptty /bye




  
Now start a new shell and everything will start up. 
To get the public ssh key off the yubikey (like to install it on github): 


























wyllie@supercollider:~ $ ssh-add -L
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC.....TJQQ2uCF45jiQ== cardno:000001234567 




  
Then cut and paste that into the github ssh key page, or into authorized_hosts on any machines you ssh into. 
YubiSwitch 
The YubiSwitch software runs on MacOsX only. It's a very simple program that runs in the system tray and allows you to activate the yubikey for a short amount of time by either clicking on the yubikey icon or by typing a keyboard sequence. the advantage is that you avoid having the yubikey sending text like 'cccccchnfcguhjriktkddvhtudijdnuikrdbfdigufdv' to terminal windows when you accidentally touch the key. Another nice feature is that the key will still activate automatically when connecting to AWS, GitHub or any other service that uses the hardware key. 
Yubico Authenticator 
The authenticator app gives you rotating, six digit, one time passwords that are commonly using on many websites for 2FA. The advantage to using this program is that the keys used to generate the codes are stored securely on the yubikey and will only show up if the yubikey is installed on your system. This is similar to using the Google Authenticator on your phone to generate One Time Passwords. 
Download here: https://www.yubico.com/products/services-software/download/yubico-authenticator/