From cc6af642248f2c1302afcb84668214c0b4f25c38 Mon Sep 17 00:00:00 2001 From: Justin W. Flory Date: Aug 31 2017 23:36:24 +0000 Subject: Add pandoc-ified wiki page that will need a lot of love --- diff --git a/en-US/Infrastructure_Yubikey.adoc b/en-US/Infrastructure_Yubikey.adoc new file mode 100644 index 0000000..8ba54c1 --- /dev/null +++ b/en-US/Infrastructure_Yubikey.adoc @@ -0,0 +1,125 @@ +[[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.