+ [[yubikeys]]

+ 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]]

+ 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]]

+ 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]]

+ 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]]

+ 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]]

+ 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]]

+ 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-ive-lost-my-yubikey]]

+ 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.