===== Using a YubiKey as two-factor authentication for Debian desktops =====

This guide will show you how to use your YubiKey as a hardware crypto device for local logins. This will not replace your login password, but it will only allow your user account to log in if the YubiKey is present. If not, any password you enter (including the correct one) will be considered "wrong".

An "attacker" (or really, some guy in the office trying to guess your password) would not be able to see any difference between a genuinely wrong password or the YubiKey not being plugged in.

----
\\


==== Adding a challenge response slot to your YubiKey ====

You will probably use OTP functionality (using HID emulation) in the first slot. This requires constant queries to a server, which is not really ideal for logging in to a local machine. (Let's say you're not connected to the internet all the time.) However, you can also add a challenge response slot next to the OTP slot, which works locally and does not depend on back-end servers. (It also isn't affected by scancode problems Dvorak users have to deal with.)

For this, you will need the YubiKey Personalization tool in Debian/main:


<code bash>sudo apt install yubikey-personalization</code>

Make sure your YubiKey is plugged in, and run this command (the ''-2'' stands for slot 2):

<code bash>ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible</code>

And commit with ''Y''.

----
\\


==== Creating a challenge file ====

Now you have your YubiKey set up, it is time to create a challenge file. This requires the ''ykpamcfg'' tool from Debian/main:

<code bash>sudo apt install libpam-yubico</code>

Run this command afterwards:

<code bash>ykpamcfg -2 -v</code>

This will create a file in ''~/.yubico'' called ''challenge-$serialnumber''.

Rename the ''challenge'' part to your user name. So for instance, if your user name is ''cindy'' and the serial number of your YubiKey is ''246837'', run:

<code bash>mv ~/.yubico/challenge-246837 ~/.yubico/cindy-246837</code>
\\

=== Placing the challenge file ===

It's best to move the challenge file outside of your user directory (for instance, you might be using ecryptfs) and set strong permissions.

<code bash>
sudo mv ~/.yubico /var/yubico
sudo chown -R root:root /var/yubico
sudo chmod 700 /var/yubico
sudo chmod 600 /var/yubico/cindy-246837
</code>

----
\\


==== Setting up PAM ====

First off, open a root terminal in case you mess it up.

<code bash>sudo -s</code>

Then, open **another** terminal and run:

<code bash>sudo dpkg-reconfigure libpam-yubico</code>

When it asks for the configuration line, delete everything and add this:

<code bash>mode=challenge-response chalresp_path=/var/yubico</code>

Then hit ''<Ok>''.

Now it will ask you to select the PAM profiles you wish to enable.

Make sure that the ''Yubico authentication with YubiKey'' option is enabled (''[*]'') and hit ''<Ok>''.

----
\\


==== Testing the authentication ====

Remove your YubiKey and open a **new** terminal. Then try to become root with ''sudo'':

<code bash>sudo -s</code>

Enter your password. It should print ''Sorry, try again.'' even though your password is correct.

Hit ''Ctrl+C'' and plug in your YubiKey. Then try again:

<code bash>sudo -s</code>

Enter your password. It should now show a root prompt.\\
\\


=== Session logins ===

This same mechanism also works with tty logins, display managers and lock screens. Your YubiKey **must** be present for any password to work. And if you plug in your YubiKey after starting the authentication (in GDM, this means clicking your user name), you must cancel it first and retry with the YubiKey present.

----