From Fedora Project Wiki

(Remove unnessesary line breaks and rewrite website section)
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
= Using a Yubikey with Fedora =
 
= Using a Yubikey with Fedora =
 
+
{{needs love}}
This document describes how to use a Yubikey to authenticate to your machines
+
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.
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
+
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/.
(OTPs). They are created and sold via a company called Yubico -
 
http://yubico.com/.
 
  
For more information about yubikey features, see their product page -
+
For more information about yubikey features, see their product page - https://yubico.com/products/
http://yubico.com/products/yubikey/
 
  
 
= How do I get a yubikey? =
 
= How do I get a yubikey? =
Line 20: Line 15:
 
= 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
+
There are two main ways to configure the yubikey PAM module to authenticate users, via the YubiCloud, or using challenge-response. The YubiCloud is the standard method, and involves leveraging Yubico's cloud to validate your yubikey. While this guide will cover the YubiCloud method, it is worth looking into challenge-response if you do not trust the YubiCloud, or will not always have an internet connection.
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
+
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.
13, you can install the pam_yubico package by running
+
 
 +
First, we need to install the required software. Since Fedora 18 you can install the pam_yubico package by running
 
<pre>
 
<pre>
su -c "yum install pam_yubico"
+
sudo dnf install pam_yubico
 
</pre>
 
</pre>
  
Next, we need to configure PAM (Pluggable Authentication Modules, the main
+
Next, we need to configure PAM (Pluggable Authentication Modules, the main Linux authentication mechanism) to accept a Yubikey as a means of authentication. For our example setup, we will first accept a Yubikey OTP as 'sufficient'. This means that a Yubikey alone is enough to authenticate a
Linux authentication mechanism) to accept a Yubikey OTP as a means of
+
user.  
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
+
Open /etc/pam.d/login with your editor of choice. This guide will use nano.
user. Adding the following line to /etc/pam.d/login, right above the line that
+
<pre>
reads ''auth include system-auth'', will do the trick:
+
sudo nano /etc/pam.d/login
 +
</pre>
 +
Find the line that reads "auth substack system-auth". Above that, insert the following:
 
<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
+
Do not worry about id and authfile right now, we will configure them later. Mind that the ''debug'' part is purely so we can see some output, and can be removed after the yubikey is setup.
''debug'' part is purely so we can see some output, it is not necessary in
+
 
production use.
+
Now we have a PAM configuration that will accept Yubikey as a means of user authentication. Next we will tell it which user is authenticated by which yubikey using the "authfile" option.
 +
 
 +
The ''authfile'' option makes it easy to centrally map yubikeys to users. More information about "authfile" can be found at the following link under "Authorization Mapping Files": https://developers.yubico.com/yubico-pam/.
  
So now we have a PAM configuration that'll accept Yubikey OTPs as a means of
+
Open /etc/yubikeys in an editor.
user authentication. But how to tell it which user is authenticated by what
+
<pre>
Yubikey's OTPs? That is what the ''authfile'' option is for.
+
sudo nano /etc/yubikeys
 +
</pre>
  
The ''authfile'' option, though undocumented for the version of pam_yubico that
+
You will now need to add mappings in the format of <uid>:<yubikey_token_id>. The easiest way to find the token ID is to remove the trailing 32 characters of an OTP (the characters spit out when a yubikey is tapped). Here is what an authfile might look like:
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
 
harry:cclcclcclccl
 
harry:cclcclcclccl
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.
 
  
Alternatively, you can allow your users to make their own mappings. Just leave
+
This file designates that the "root" user will be paired with the yubikey with the "cccccccccccc", and the "harry" user will be authenticated with the "cclcclcclccl" yubikey. You may add multiple yubikeys to a user by separating the token IDs with a colon. For example, here we will allow the "root" yubikey to also authenticate "harry":
off the ''authfile'' option to pam_yubico.so. Tell your users to create a
+
<pre>
.yubico directory in their home directory and make a mapping file in it called
+
root:cccccccccccc
authorized_yubikeys. This and the authfile option are mutually exclusive.
+
harry:cclcclcclccl:cccccccccccc
 +
</pre>
 +
 
 +
Alternatively, you can allow your users to make their own mappings. Just remove 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
 
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.
 
the nice debug output when we log in.
  
{{admon/note|Note that if you have SELinux on the enforcing mode, you should flip on the
+
{{admon/note|Note that if you have SELinux on the enforcing mode (the default mode), you should flip on the allow_ypbind boolean first, because pam_yubico needs to be able to connect to
allow_ypbind boolean first, because pam_yubico needs to be able to connect to
 
 
Yubico's online authentication servers.
 
Yubico's online authentication servers.
 
<pre>
 
<pre>
setsebool -P allow_ypbind=1
+
sudo setsebool -P allow_ypbind=1
 
</pre>
 
</pre>
 
Also, in order to allow sshd to access /root/.yubico/authorized_yubikeys, you should change its context:
 
Also, in order to allow sshd to access /root/.yubico/authorized_yubikeys, you should change its context:
Line 81: Line 74:
 
}}
 
}}
  
Open a console, type one of the usernames you mapped a Yubikey to, press the
+
With this done, you should be all ready to go! The next time you open a console (local, not ssh session) and attempt to login you should me prompted "Yubikey for '<user>':". Tap your yubikey to input an OTP and, hopefully, you will be logged in successfully.
Yubikey's button and you should be good to go.
+
 
 +
Once you have verified things are working, feel free to remove the "debug" parameter from /etc/pam.d/login so that you won't get the debug logging in your console.
 +
 
 +
= Additional Configuration =
 +
There are a number of common things people might want to configure their yubikey to do. In this section we will cover those.
 +
 
 +
== Requiring both yubikey and password ==
  
For extra security, you can add an extra "url" option to pam_yubico.so line in
+
In the previous section we configured the yubikey to be a replacement for users' passwords. However, there are times in which you may want both a yubikey and a password to be required. To accomplish this, we change the pam_yubico.so lines in /etc/pam.d/* to read 'required' instead of 'sufficient', like below:
/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 required pam_yubico.so id=1 authfile=/etc/yubikeys
 
</pre>
 
</pre>
  
Lastly, if we want to have multi-factor authentication, we change the
+
Now you'll be queried for both Yubikey OTP and your normal password at login!
pam_yubico.so lines in /etc/pam.d/login and /etc/pam.d/sshd to read 'required'
+
 
instead of 'sufficient', like below:
+
== Using a yubikey for more than login ==
 +
 
 +
We have configured the yubikey to be used in regular logins, but many users would like to use their yubikeys for tasks such as ssh and root elevation. In order to accomplish this, we must copy the pam_yubico.so line we've written into the other PAM modules we wish to integrate with.
 +
 
 +
As a reminder, here is our line we've been using:
 
<pre>
 
<pre>
auth required pam_yubico.so id=1 url=https://api.yubico.com/wsapi/verify?id=%d&otp=%s
+
auth sufficient pam_yubico.so id=1 authfile=/etc/yubikeys
 
</pre>
 
</pre>
  
Now you'll be queried for both Yubikey OTP and your normal password at login!
+
To allow using a yubikey to authenticate with sudo, add our line to the file "/etc/pam.d/sudo".
 +
 
 +
To allow using a yubikey to authenticate with sshd, add our line to the file "/etc/pam.d/sshd".
  
 
= Customizing a Yubikey with Fedora =  
 
= Customizing a Yubikey with Fedora =  
  
A Yubikey generates OTPs by encrypting an internally generated string
+
A Yubikey generates OTPs by encrypting an internally generated string (containing a counter, among 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: https://www.yubico.com/wp-content/uploads/2015/03/YubiKeyManual_v3.4.pdf.
(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:
 
https://www.yubico.com/wp-content/uploads/2015/03/YubiKeyManual_v3.4.pdf.
 
  
 
Before we start, we need to install the appropriate software to customize Yubikeys, by running
 
Before we start, we need to install the appropriate software to customize Yubikeys, by running
Line 115: Line 114:
 
== Writing a new static password to the second slot of the key ==
 
== Writing a new static password to the second slot of the key ==
  
Newer Yubikeys (the Yubikey 2) have the ability to store two separate
+
Newer Yubikeys (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
configurations. The first is generally used for OTPs, the second for a strong,
+
longer, in the range of 2.5 to 5 seconds, the second configuration is triggered.
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
+
For this first example we are going to write a new static key to the second configuration of a Yubikey 2.  
configuration of a Yubikey 2.  
 
  
 
<pre>
 
<pre>
Line 129: Line 123:
 
</pre>
 
</pre>
  
This writes a static key to the Yubikey based on the 32-byte AES key I gave
+
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.
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 ==
 
== 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
+
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, remember what the values are that you use below. You will need them later on.
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>
 
<pre>
Line 148: Line 133:
 
</pre>
 
</pre>
  
The -1 option tells ykpersonalize to use the first configuration. The fixed
+
The -1 option tells ykpersonalize to use the first configuration. The fixed option specifies the public ID of the Yubikey. This is referred 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.
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
+
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.
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
+
The -a option, again, is the 32-byte AES key and append-cr appends a carriage return to my key as the last character.
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
 
When I hit the <ENTER> key, the ykpersonalize program will present me with my options and ask for
Line 183: Line 160:
 
=== What is modhex? ===
 
=== What is modhex? ===
  
When plugged in, the operating system treats the Yubikey as a USB keyboard. USB
+
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',
keyboards send scancodes to the operating system, which the operating
+
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.
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 ==
  
If you want to customize your Yubikey's AES key but still want to use it to
+
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 https://upgrade.yubico.com/getapikey/. You will need to enter your email address and Yubikey's OTP.
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 =
 
= Using the Yubikey to authenticate to websites =
  
If you want to use your Yubikey to authenticate to websites, you do this at
+
As of 2019, there is work in place to attempt to standardize using a yubikey on the web. The new standard is called WebAuthn, and you can learn more about it here: https://www.yubico.com/solutions/webauthn/. For now, the easiest way to see which platforms support the yubikey is by browsing yubico's catalog at https://www.yubico.com/works-with-yubikey/catalog/.
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.
 

Latest revision as of 15:49, 12 June 2019

Using a Yubikey with Fedora

Cog.png
This page needs some love
This page should be revised or reconstructed to be more helpful. Problems may include being out of step with current team or project status or process.

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 - https://yubico.com/products/

How do I get a yubikey?

You can purchase a yubikey from Yubico's website - http://store.yubico.com/.

Using a Yubikey to authenticate to a machine running Fedora

There are two main ways to configure the yubikey PAM module to authenticate users, via the YubiCloud, or using challenge-response. The YubiCloud is the standard method, and involves leveraging Yubico's cloud to validate your yubikey. While this guide will cover the YubiCloud method, it is worth looking into challenge-response if you do not trust the YubiCloud, or will not always have an internet connection.

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. Since Fedora 18 you can install the pam_yubico package by running

sudo dnf install pam_yubico

Next, we need to configure PAM (Pluggable Authentication Modules, the main Linux authentication mechanism) to accept a Yubikey as a means of authentication. For our example setup, we will first accept a Yubikey OTP as 'sufficient'. This means that a Yubikey alone is enough to authenticate a user.

Open /etc/pam.d/login with your editor of choice. This guide will use nano.

sudo nano /etc/pam.d/login

Find the line that reads "auth substack system-auth". Above that, insert the following:

auth sufficient pam_yubico.so debug id=1 authfile=/etc/yubikeys 

Do not worry about id and authfile right now, we will configure them later. Mind that the debug part is purely so we can see some output, and can be removed after the yubikey is setup.

Now we have a PAM configuration that will accept Yubikey as a means of user authentication. Next we will tell it which user is authenticated by which yubikey using the "authfile" option.

The authfile option makes it easy to centrally map yubikeys to users. More information about "authfile" can be found at the following link under "Authorization Mapping Files": https://developers.yubico.com/yubico-pam/.

Open /etc/yubikeys in an editor.

sudo nano /etc/yubikeys

You will now need to add mappings in the format of <uid>:<yubikey_token_id>. The easiest way to find the token ID is to remove the trailing 32 characters of an OTP (the characters spit out when a yubikey is tapped). Here is what an authfile might look like:

root:cccccccccccc
harry:cclcclcclccl

This file designates that the "root" user will be paired with the yubikey with the "cccccccccccc", and the "harry" user will be authenticated with the "cclcclcclccl" yubikey. You may add multiple yubikeys to a user by separating the token IDs with a colon. For example, here we will allow the "root" yubikey to also authenticate "harry":

root:cccccccccccc
harry:cclcclcclccl:cccccccccccc

Alternatively, you can allow your users to make their own mappings. Just remove 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.png
Note that if you have SELinux on the enforcing mode (the default mode), you should flip on the allow_ypbind boolean first, because pam_yubico needs to be able to connect to

Yubico's online authentication servers.

sudo setsebool -P allow_ypbind=1

Also, in order to allow sshd to access /root/.yubico/authorized_yubikeys, you should change its context:

chcon -R system_u:object_r:ssh_home_t:s0 /root/.yubico

With this done, you should be all ready to go! The next time you open a console (local, not ssh session) and attempt to login you should me prompted "Yubikey for '<user>':". Tap your yubikey to input an OTP and, hopefully, you will be logged in successfully.

Once you have verified things are working, feel free to remove the "debug" parameter from /etc/pam.d/login so that you won't get the debug logging in your console.

Additional Configuration

There are a number of common things people might want to configure their yubikey to do. In this section we will cover those.

Requiring both yubikey and password

In the previous section we configured the yubikey to be a replacement for users' passwords. However, there are times in which you may want both a yubikey and a password to be required. To accomplish this, we change the pam_yubico.so lines in /etc/pam.d/* to read 'required' instead of 'sufficient', like below:

auth required pam_yubico.so id=1 authfile=/etc/yubikeys

Now you'll be queried for both Yubikey OTP and your normal password at login!

Using a yubikey for more than login

We have configured the yubikey to be used in regular logins, but many users would like to use their yubikeys for tasks such as ssh and root elevation. In order to accomplish this, we must copy the pam_yubico.so line we've written into the other PAM modules we wish to integrate with.

As a reminder, here is our line we've been using:

auth sufficient pam_yubico.so id=1 authfile=/etc/yubikeys

To allow using a yubikey to authenticate with sudo, add our line to the file "/etc/pam.d/sudo".

To allow using a yubikey to authenticate with sshd, add our line to the file "/etc/pam.d/sshd".

Customizing a Yubikey with Fedora

A Yubikey generates OTPs by encrypting an internally generated string (containing a counter, among 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: https://www.yubico.com/wp-content/uploads/2015/03/YubiKeyManual_v3.4.pdf.

Before we start, we need to install the appropriate software to customize Yubikeys, by running

su -c "yum install ykpers"

Writing a new static password to the second slot of the key

Newer Yubikeys (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 range 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, remember 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 referred 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 https://upgrade.yubico.com/getapikey/. You will need to enter your email address and Yubikey's OTP.

Using the Yubikey to authenticate to websites

As of 2019, there is work in place to attempt to standardize using a yubikey on the web. The new standard is called WebAuthn, and you can learn more about it here: https://www.yubico.com/solutions/webauthn/. For now, the easiest way to see which platforms support the yubikey is by browsing yubico's catalog at https://www.yubico.com/works-with-yubikey/catalog/.