From Fedora Project Wiki

(what is modhex)
(draft 0.1 :))
Line 1: Line 1:
= Using a Yubikey with Fedora =
= 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.
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? =
= 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/.
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/
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? =
Line 13: Line 18:
You can purchase a yubikey from Yubico's website - http://store.yubico.com/.   
You can purchase a yubikey from Yubico's website - http://store.yubico.com/.   


{{admon/note|Fedora users can use discount code "Fedora20" for a 20% discount for orders less then 10 yubikeys From October 12th to December 1st 2010. }}
{{admon/note|Fedora users can use discount code "Fedora20" for a 20% discount
for orders less then 10 yubikeys From October 12th to December 1st 2010. }}


= Using a Yubikey to authenticate to a machine running Fedora =
= 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.
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
First, we need to install the required software. For a machine running Fedora
13, you can install the pam_yubico package by running
<pre>
<pre>
su -c "yum install pam_yubico"
su -c "yum install pam_yubico"
</pre>
</pre>


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:
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:
<pre>
<pre>
auth sufficient pam_yubico.so debug id=1 authfile=/etc/yubikeys  
auth sufficient pam_yubico.so debug id=1 authfile=/etc/yubikeys  
</pre>
</pre>
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.
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.  
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'':
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'':
<pre>
<pre>
root:cccccccccccc
root:cccccccccccc
Line 38: Line 59:
joe:llcllcllcllc:lclclclclclc
joe:llcllcllcllc:lclclclclclc
</pre>
</pre>
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.
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.
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.
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.


{{admon/note|Note that if you have SELinux turned on, you should flip on the allow_ypbind boolean first, because pam_yubico needs to be able to connect to Yubico's online authentication servers.
{{admon/note|Note that if you have SELinux turned on, you should flip on the
allow_ypbind boolean first, because pam_yubico needs to be able to connect to
Yubico's online authentication servers.
<pre>
<pre>
setsebool -P allow_ypbind=1
setsebool -P allow_ypbind=1
Line 50: Line 80:
}}
}}


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.
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:
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:
<pre>
<pre>
auth sufficient pam_yubico.so id=1 url=https://api.yubico.com/wsapi/verify?id=%d&otp=%s
auth sufficient pam_yubico.so id=1 url=https://api.yubico.com/wsapi/verify?id=%d&otp=%s
</pre>
</pre>


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:
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:
<pre>
<pre>
auth required pam_yubico.so id=1 url=https://api.yubico.com/wsapi/verify?id=%d&otp=%s
auth required pam_yubico.so id=1 url=https://api.yubico.com/wsapi/verify?id=%d&otp=%s
Line 66: Line 100:
= Customizing a Yubikey with Fedora =  
= 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.
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 ==
== Writing a new static password to the second slot of the key ==


For this example we are going to write
Newer Yubikeys (the Yubikey 2) have the ability to store two separate
configurations. The first is generally used for OTPs, the second for a strong,
static password. If the button is pressed shortly, something up to 1.5
seconds, the first configuration is triggered. If the button is pressed
longer, in the rango of 2.5 to 5 seconds, the second configuration is
triggered.


=== Modhex ===
For this first example we are going to write a new static key to the second
configuration of a Yubikey 2.


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.  
<pre>
sudo ykpersonalize -oappend-cr -a123456deadcafebeef65432112345678 -2 -o-man-update
</pre>
 
This writes a static key to the Yubikey based on the 32-byte AES key I gave
with the -a option. The -2 option tells it to write to the second
configuration. The other two options are a matter of personal taste. The
append-cr option sends a carriage return as the last character of the key. That
way I do not have to press <ENTER> myself. The -man-update option disables easy
updating of the static key in the Yubikey. Enabling this will allow for
altering the static password without the use of ykpersonalize.
 
== Writing a new AES key to the first slot of the key ==
 
If we want to write a new configuration to the first slot of the key, we need
to specify some more options. If you want to be able to upload you key to
Yubico, in order to authenticate against their servers, remeber what the
values are that you use below. You will need them later on.
 
<pre>
sudo ykpersonalize -1 -ofixed=vvhhhrhkhgidic -ouid=deadbeefcafe -a123456deadcfaebeef65432112345678 -oappend-cr
</pre>
 
The -1 option tells ykpersonalize to use the first configuration. The fixed
option specifies the public ID of the Yubikey. This is refered to as the
'prefix' later on, when we go uploading it. The value you use here has to
start with 'ff' in hex or 'vv' in modhex (see below at [[#What is modhex?]]).
Yubico enforces this when you try to upload your key to their servers. The value for the fixed option can
be up to 16 characters in length.
 
As part of the OTP, you can specify an internal identifier for your key. This
is what the uid option does. The value is in plain hex, not modhex and
''exactly'' 12 character long.
 
The -a option, again, is the 32-byte AES key and append-cr appends a carriage
return to my key as the last character.
 
When I hit the <ENTER> key, the ykpersonalize program will present me with my options and ask for
confirmation before continuing:
   
<pre>
Firmware version 2.1.1 Touch level 1795 Program sequence 3
Configuration data to be written to key configuration 1:
 
fixed: m:vvhhhrhkhgidic
uid: h:deadbeefcafe
key: h:123456deadcfaebeef65432112345678
acc_code: h:000000000000
ticket_flags: APPEND_CR
config_flags:
 
Commit? (y/n) [n]:
</pre>


After pressing 'y', I am able to generate OTPs with my new key!
=== What is 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 every 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 basically characters which have the same
scancode on all keyboard layouts.


== Uploading the generated AES key to Yubico ==
== Uploading the generated AES key to Yubico ==


== Writing a strong, static password to the key ==
If you want to customize your Yubikey's AES key but still want to use it to
authenticate through Yubico's servers, you can upload the key through
http://www.yubico.com/developers/aeskeys/. You will need to enter the AES key,
the prefix, the uid (what we called internal identifier above), your email address and '''the serial number of your
key'''. Don't through away the little packet in came in!
 
= Using the Yubikey to authenticate to websites =
 
If you want to use your Yubikey to authenticate to websites, you do this at
any website that supports OpenID. Yubico has it's own OpenID server at
http://openid.yubico.com/. Your Yubikey will work with it out of the box, but
it is a bit limited in options.
 
There is at least one third-party OpenID provider that accepts OpenIDs:
clavid, a security solutions provider from Switzerland. Creating an OpenID at
their website is free and they accept Yubikeys. Clavid authenticates you at
Yubico's servers, but allows you to have several identities, allows
multi-factor authentication and has a host of other authentication options
apart from the Yubikey.
 
You can find them at http://www.clavid.com.

Revision as of 21:22, 15 October 2010

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

Fedora users can use discount code "Fedora20" for a 20% discount for orders less then 10 yubikeys From October 12th to December 1st 2010.

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.

Note that if you have SELinux turned on, you should flip on the

allow_ypbind boolean first, because pam_yubico needs to be able to connect to Yubico's online authentication servers.

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 static password to the second slot of the key

Newer Yubikeys (the Yubikey 2) have the ability to store two separate configurations. The first is generally used for OTPs, the second for a strong, static password. If the button is pressed shortly, something up to 1.5 seconds, the first configuration is triggered. If the button is pressed longer, in the rango of 2.5 to 5 seconds, the second configuration is triggered.

For this first example we are going to write a new static key to the second configuration of a Yubikey 2.

sudo ykpersonalize -oappend-cr -a123456deadcafebeef65432112345678 -2 -o-man-update

This writes a static key to the Yubikey based on the 32-byte AES key I gave with the -a option. The -2 option tells it to write to the second configuration. The other two options are a matter of personal taste. The append-cr option sends a carriage return as the last character of the key. That way I do not have to press <ENTER> myself. The -man-update option disables easy updating of the static key in the Yubikey. Enabling this will allow for altering the static password without the use of ykpersonalize.

Writing a new AES key to the first slot of the key

If we want to write a new configuration to the first slot of the key, we need to specify some more options. If you want to be able to upload you key to Yubico, in order to authenticate against their servers, remeber what the values are that you use below. You will need them later on.

sudo ykpersonalize -1 -ofixed=vvhhhrhkhgidic -ouid=deadbeefcafe -a123456deadcfaebeef65432112345678 -oappend-cr

The -1 option tells ykpersonalize to use the first configuration. The fixed option specifies the public ID of the Yubikey. This is refered to as the 'prefix' later on, when we go uploading it. The value you use here has to start with 'ff' in hex or 'vv' in modhex (see below at #What is modhex?). Yubico enforces this when you try to upload your key to their servers. The value for the fixed option can be up to 16 characters in length.

As part of the OTP, you can specify an internal identifier for your key. This is what the uid option does. The value is in plain hex, not modhex and exactly 12 character long.

The -a option, again, is the 32-byte AES key and append-cr appends a carriage return to my key as the last character.

When I hit the <ENTER> key, the ykpersonalize program will present me with my options and ask for confirmation before continuing:

Firmware version 2.1.1 Touch level 1795 Program sequence 3
Configuration data to be written to key configuration 1:

fixed: m:vvhhhrhkhgidic
uid: h:deadbeefcafe
key: h:123456deadcfaebeef65432112345678
acc_code: h:000000000000
ticket_flags: APPEND_CR
config_flags: 

Commit? (y/n) [n]:

After pressing 'y', I am able to generate OTPs with my new key!

What is 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 every 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 basically characters which have the same scancode on all keyboard layouts.

Uploading the generated AES key to Yubico

If you want to customize your Yubikey's AES key but still want to use it to authenticate through Yubico's servers, you can upload the key through http://www.yubico.com/developers/aeskeys/. You will need to enter the AES key, the prefix, the uid (what we called internal identifier above), your email address and the serial number of your key. Don't through away the little packet in came in!

Using the Yubikey to authenticate to websites

If you want to use your Yubikey to authenticate to websites, you do this at any website that supports OpenID. Yubico has it's own OpenID server at http://openid.yubico.com/. Your Yubikey will work with it out of the box, but it is a bit limited in options.

There is at least one third-party OpenID provider that accepts OpenIDs: clavid, a security solutions provider from Switzerland. Creating an OpenID at their website is free and they accept Yubikeys. Clavid authenticates you at Yubico's servers, but allows you to have several identities, allows multi-factor authentication and has a host of other authentication options apart from the Yubikey.

You can find them at http://www.clavid.com.