For those of you who have not yet encountered a Yubikey, it is a physically small security key which empowers passwordless or 2-factor authentication in a number of different scenarios. They now support a huge number of protocols including One Time Passwords, NFC, FIDO2, U2F, Smart card, and OpenPGP.
Mine has been living on my keyring for several years now, and has proved invaluable for me accessing both my physical and electronic world.
What is Yubikey?
A Yubikey from Yubico is a small, robust, device which you can carry on your keyring. Once plugged in to a USB port it acts as a simple keyboard emulator – pressing the touch sensitive button on the top will send a stream of characters followed by a carriage return to whichever app is currently active.
This simple emulation generates a OTP (One-Time Password) to the OATH standards. You can see in a terminal window that the OTP changes on each successive generation (note that the first 12 characters I’ve highlighted are always the same and constitute the ID of the Yubikey).
user@host:~# vvfujinjabcdeleuivfiufruftlberifrbjvcffkflne user@host:~# vvfujinjabcdvvkfugtrrhvnnunbnlgcbjkfgjnduidt user@host:~# vvfujinjabcdrriktbtuljfjuinhhfkildjlkciegdkr user@host:~# vvfujinjabcdnbdirdbhdtgiidfkecuueikgkbhbjdlb
The latest products like the Yubikey 5 can do much more than that, but for the purposes of this tutorial we shall concentrate on using the Yubikey with PAM (Linux Pluggable Authentication Modules).
Scenario
If you have followed my Fail2ban tutorial you will know that servers on a publicly accessible IPs are easy targets for the bots trying to access SSH and other services. Of course strong passwords are your first defence against such attacks, and I’m sure many of you will have configured authorized key access for SSH, but what if you need to be able to shell onto a host from trusted locations where you don’t have your keys?
I will show you below how to configure Yubikey into the SSH PAM stack as a compliment to shared keys. Note: You could lock yourself out of a host if you get this configuration wrong, so I’d strongly suggest having an alternate method of access (e.g. authorized keys) before proceeding.
It is important to remember that the OTP is just one of the authentication factors and the other is your existing system password.
Installation and Configuration
Most modern Linux distributions have the required modules in their package mamagers. I shall be using Debian, but configuration files will be in broadly the same place on Fedora or FreeBSD.
user@host:~# apt-get install libpam-yubico
One of the requirements is to maintain a map between the Yubikey ID and the system username. This file I create as /etc/yubico and should look similar to below.
# Username : Yubikey ID simon:vvfujinjabcd
Obviously your username and ID will differ from mine – to get your key simply plug in your Yubikey, make sure a text editor is the active window and press the button. The first 12 characters generated are your ID. Users can have multiple IDs by adding them all on the same line separated by colons.
The PAM module will by default use the Yubico servers to validate the OTP entered, and any unboxed key will already be know to the servers. But it you have reprogrammed the key for any reason you will need to re-register with the key servers. Note that you do not need the APi key for pam to access the services.
Now insert the following into the top of/etc/pam.d/sshd so that it is the top of the stack. Yubikeys support multiple identifies but we shall use the default for ease.
#yubico auth sufficient pam_yubico.so id=1 authfile=/etc/yubico
Finally, make sure that ssh is properly configured by editing /etc/ssh/sshd_config and making sure that the following settings are enabled
ChallengeResponseAuthentication yes UsePAM yes
Restart the ssh service and start testing. If it is a remote host I would suggest keeping one session connected in case you have any issues.
root@host:~# service ssh restart
Testing
Fire up a new local terminal and connect to your host (making sure that your Yubikey is plugged in). If you have authorized key access configured then you can bypass that on the command line as follows.
user@host:~# ssh -o PreferredAuthentications=password simon@hostname.example.com
and you should be presented with your password prompt. Now enter the system password for the user you are connecting as, then press the button on the Yubikey. The OTP and a carriage return will be sent and you will be logged in
simon@hostname.example.com's password: MOTD simon@hostname:~#
Footnote
Yubico and YubiKey are registered trademarks of Yubico.