Infrastructure/Yubikey

= Yubikeys =

Fedora officially supports yubikey authentication for some services. This document outlines what yubikeys are and how to use them. Please direct any questions or comments to #fedora-admin on irc.freenode.net.

= What is a yubikey? =

A Yubikey is a small USB based device that generates one time passwords. 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/. Note, for most fedora contributors, a yubikey is a completely optional device. This means that most contributors will be able to access everything they need to contribute to Fedora without needing a yubikey. See the "What are yubikeys used for?" section below for more information.

= How do they work =

Yubikeys have a few different operating modes. Some models can store multiple password types. The most common is a single touch OTP generation. Once your yubikey has been burned and stored in FAS you can begin using it. The basic function is this:


 * 1) Plug in yubikey
 * 2) Try to log in to some service.
 * 3) When asked for password, place the cursor in the password field and touch the round button on the yubikey.
 * 4) Upon touching the button the key will type its OTP into the password field and hit enter, thus logging you in.

A OTP looks like this:

ccccccctfivjlfdddbkgutkkrrtgabehatcrbagrczzl

The first 12 digits are your key identifier. The rest contains encrypted random bits, other info and most importantly, a serial number. Every use of the yubikey increases this number by one. If you happen to put an OTP in IRC or something, just log in to something in Fedora via a yubikey and the old one will be invalidated.

= What are yubikeys used for? =

Fedora is using Yubikeys for a couple of things. Most people will be able to use yubikeys to log in to our websites or gain shell access on some machines.

For example, users currently using ssh keys to log in to fedorapeople.org are now able to log in with a yubikey. The ssh key will continue to work, its just yubikeys are an added option. Additionally, most users use their username and password to log in to say bodhi. Users will now be able to log in using their yubikey if they wish.

There are, however, some higher security hosts that will require yubikey auth. For any services where yubikeys are required auth, the Fedora Project will provide yubi keys for those users / admins. An example of this could be the signing servers.

= How are yubikeys more secure? =

The security in yubikeys are their one time password (OTP) features. If someone sniffs your OTP over the wire, it won't be as useful to them as a regular password since the password only works once. And, in theory, since it just went over the wire. It just got used and won't work again in the future.

In some ways they are less secure, for example if someone were to steal your yubikey then they could log in to services with it. For this reason, our higher security hosts we'll be requiring multiple factor authentication. Meaning someone would need to know a username and password, and have the yubikey in order to get in. This two factor auth is common practice and details in Fedora's infrastructure are always being evaluated and discussed.

= How do I burn my yubikey? =

In order to use your yubikey in Fedora it must first be customized first. These steps will burn your yubikey. NOTE: This will remove any previous keys from the yubikey.


 * 1) Plug in your yubikey.
 * 2) Install the fedora-packager (which version?) package via yum or packagekit
 * 3) As root run /usr/sbin/fedora-burn-yubikey -u $YOUR_USERNAME
 * 4) When asked for y/n.  Tell it y.
 * 5) Log in to https://admin.fedoraproject.org/accounts/yubikey/ with your username and regular password
 * 6) Click edit
 * 7) Set "Active" to "Enabled"
 * 8) Place the cursor in "Key Prefix" and press your yubikey button.  (You could also just type the first 12 digits of yubikey manually.
 * 9) Put your cursor into the 'Test Auth:' box and press your yubikey button.

Step 10 is a test of your yubikey. If it all works, you should see "Yubikey auth success." You should now be able to log in to our yubi-key provided services.

Should you want to re-burn your key at any time. Simply re-do steps 3 and 4 above.

= Help! I've lost my yubikey =

If you've lost your yubikey or you think someone has stolen it. Immediately email admin@fedoraproject.org to let them know so they can watch for any strange activity. Then log in with your regular username and password to: https://admin.fedoraproject.org/accounts/yubikey/ Then click edit and disable your yubikey auth by setting "Active" to "Disabled". You can then program a new key (this will invalidate the old key) and then set active back to enabled.