Infrastructure/Yubikey

Yubikeys

Fedora officially supports yubikey authentication for a second factor with sudo on fedora infrastructure machines. Planning is being done to enable yubikeys as a second factor in web applications and the like, but is not yet in place. 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 was using yubikeys as a single factor, allowing users to login with the yubikey instead of a password for websites and applications. This access has been discontinued now and yubikeys are only currently being used for sudo access on some infrastructure machines.

Planning is underway to re-enable web applications to use yubikey as a second factor (in addition to password), but this support is not yet implemented or in place.

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, we have disabled single factor authentication with yubikeys and require two factor (password + yubikey).

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 dnf or packagekit
3. As root run /usr/sbin/fedora-burn-yubikey -u $YOUR_USERNAME. Caution: By default the tool will overwrite the first slot of your yubikey. The first slot is a factory burned OTP, which some applications regard as more secure than custom OTP uploads. You can't use the Fedora OTP for services other than FAS. Therefore you can't upload the FAS OTP to Yubico since you don't have knowledge of the private OTP properties, only the FAS infrastructure does. Reverting to a custom OTP will give you the 'cc' OTP prefix, which some applications deem less secure. To prevent overwriting the first slot of your yubikey, use the second slot of your yubikey. This can be done with the command /usr/sbin/fedora-burn-yubikey -u $YOUR_USERNAME -S 2.
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 and disable your key.