Using a Yubikey with Fedora
This document describes how to use a Yubikey to authenticate to your machines running Fedora, how to customize your Yubikey and how to use a Yubikey to authenticate to various web services by means of OpenID.
What is a yubikey?
A Yubikey is a small USB based device that generates one time passwords (OTPs). They are created and sold via a company called Yubico - http://yubico.com/.
For more information about yubikey features, see their product page - http://yubico.com/products/yubikey/
How do I get a yubikey?
You can purchase a yubikey from Yubico's website - http://store.yubico.com/.
Using a Yubikey to authenticate to a machine running Fedora
This part of this document assumes you have a machine running Fedora and you have root access over SSH or through the console. TODO: Add a little something about gdm / kdm based logins below.
First, we need to install the required software. For a machine running Fedora 13, you can install the pam_yubico package by running
su -c "yum install pam_yubico"
Next, we need to configure PAM (Pluggable Authentication Modules, the main Linux authentication mechanism) to accept a Yubikey OTP as a means of authentication. For our example setup, we will first accept a Yubikey OTP as 'sufficient'. This means that a Yubikey OTP alone is enough to authenticate a user. Adding the following line to /etc/pam.d/login, right above the line that reads auth include system-auth, will do the trick:
auth sufficient pam_yubico.so debug id=1 authfile=/etc/yubikeys
You can do the same later with /etc/pam.d/sshd, for example. Mind that the debug part is purely so we can see some output, it is not necessary in production use.
So now we have a PAM configuration that'll accept Yubikey OTPs as a means of user authentication. But how to tell it which user is authenticated by what Yubikey's OTPs? That is what the authfile option is for.
The authfile option, though undocumented for the version of pam_yubico that ships with Fedora 13, makes it easy to centrally map certain Yubikeys to certain user accounts. Just create the file /etc/yubikeys and write lines in it like this, mapping users to Yubikey token ID's:
root:cccccccccccc harry:cclcclcclccl joe:llcllcllcllc:lclclclclclc
You can find a key's token ID by creating an OTP with it and taking the first twelve characters. As illustrated above, you can map more than one Yubikey to a single user. It's also possible to map a single Yubikey to more than one user, but that is most often undesirable.
Alternatively, you can allow your users to make their own mappings. Just leave off the authfile option to pam_yubico.so. Tell your users to create a .yubico directory in their home directory and make a mapping file in it called authorized_yubikeys. This and the authfile option are mutually exclusive.
So, let's try it out. Let's start with a console login, because then we can see the nice debug output when we log in.
setsebool -P allow_ypbind=1
Open a console, type one of the usernames you mapped a Yubikey to, press the Yubikey's button and you should be good to go.
For extra security, you can add an extra "url" option to pam_yubico.so line in /etc/pam.d/login and sshd, and use Yubico's authentication servers over HTTPS:
auth sufficient pam_yubico.so id=1 url=https://api.yubico.com/wsapi/verify?id=%d&otp=%s
Lastly, if we want to have multi-factor authentication, we change the pam_yubico.so lines in /etc/pam.d/login and /etc/pam.d/sshd to read 'required' instead of 'sufficient', like below:
auth required pam_yubico.so id=1 url=https://api.yubico.com/wsapi/verify?id=%d&otp=%s
Now you'll be queried for both Yubikey OTP and your normal password at login!
Customizing a Yubikey with Fedora
A Yubikey generates OTPs by encrypting an internally generated string (containing a counter, amongst others) with an AES key. The AES key is stored on the device, together with an identifier and a counter. The complete picture of what is on the key is painted in detail in the Yubikey manual, which you can download at http://yubico.com/files/YubiKey_manual-2.0.pdf.
Writing a new AES key onto the key
For this example we are going to write
Modhex
When plugged in, the operating system treats the Yubikey as a USB keyboard. USB keyboards send scancodes to the operating system, which the operating system then interprets as keystrokes. The Yubikey has to make sure no ambiguity arises: there are many different kinds of keyboard layouts and the scancodes have to be interpreted as the same character on machines using random keyboard layout out there. To fix this, the people of Yubico have created 'modhex', which is a modified representation of hexadecimal characters that uses only 'safe' characters. 'Safe' characters are characters which have the same scancode on all keyboard layouts.