User:Mparfeni

Whats is Yubikey

Yubikey

The YubiKey is a hardware authentication device manufactured by Yubico that supports one-time passwords, public key encryption and authentication, and the Universal 2nd Factor (U2F) protocol developed by the FIDO Alliance (FIDO U2F). It allows users to securely log into their accounts by emitting one-time passwords or using a FIDO-based public/private key pair generated by the device. YubiKey also allows for storing static passwords for use at sites that do not support one-time passwords. Facebook uses YubiKey for employee credentials, and Google supports it for both employees and users. Some password managers support YubiKey.

Yubikey features

Let's take a look at the options a YubiKey provides:

• Yubico One-Time Password (OTP) The YubiKey generates an encrypted password that can only be used once
• OATH – HOTP (EVENT)
• OATH – TOTP (TIME)
• Challenge and Response (HMAC-SHA1, Yubico OTP)
• PIV-Compatible Smart Card
• OpenPGP
• FIDO U2F
• Static passwords

Two-factor authentication with SSH

This details how to use a Yubikey to have two-factor authentication with SSH, that is, to use both a password and a Yubikey-generated OTP.

Prerequisites

Install yubico-pam.

Configuration

Authorization Mapping Files

A mapping must be made between the YubiKey token ID and the user ID it is attached to. There are two ways to do this, either centrally in one file, or individually, where users can create the mapping in their home directories. If the central authorization mapping file is being used, user home directory mappings will not be used and vice versa.

Central authorization mapping

Create a file /etc/yubico/authorized_yubikeys, the file must contain a user name and the Yubikey token ID separated by colons (same format as the passwd file) for each user you want to allow onto the system using a Yubikey.

The mappings should look like this, one per line:

<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...

You can specify multiple key tokens to correspond to one user, but only one is required.

Per-user authorization mapping

Each user creates a ~/.yubico/authorized_yubikeys file inside of their home directory and places the mapping in that file, the file must have only one line:

<user name>:<Yubikey token ID1>:<Yubikey token ID2>

This is much the same concept as the SSH authorized_keys file.

Note that this file must be readable by the pam_yubico module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.

Obtaining the Yubikey token ID (a.k.a. public ID)

You can obtain the Yubikey token ID in several ways. One is by removing the last 32 characters of any OTP (One Time Password) generated with your Yubikey. Another is by using the modhex calculator.

Enter your Yubikey OTP and convert it, your Yubikey token ID is 12 characters and listed as:

Modhex encoded: XXXXXXX

PAM configuration

Having set up the pam_yubico module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.

The default way

Obtain HMAC credentials from Yubico as described in #YubiCloud and validation servers. You will receive a Client ID and a secret key.

Add one of the two following lines to the beginnning of /etc/pam.d/sshd:

auth            required      pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys

if you're using a central authorization mapping file, or

auth            required      pam_yubico.so id=CLIENTID

if you're using per-user authorization mapping, where CLIENTID} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.

Using pure HMAC to authenticate the validation server

Add key to the above lines in /etc/pam.d/sshd:

auth            required      pam_yubico.so id=CLIENTID key=SECRETKEY ...

where CLIENTID and SECRETKEY are your HMAC ID and key.

You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:

# chmod o-r /etc/pam.d/sshd

Using pure HTTPS to authenticate the validation server

If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting CLIENTID=1 instead of your own ID. Although pam_yubico's default server uses HTTPS already, for security reasons you should specify it manually via the urllist parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the debug parameter to the auth line.

SSHD configuration

You should check that /etc/ssh/sshd_config contains these lines and that they are not commented. The sshd_config shipped with openssh has these set correctly by default.

ChallengeResponseAuthentication no
UsePAM yes

That is it!

You should not need to restart anything if you did not change the SSHD config file.

To log in, at the Password: prompt of SSH, you have to type your password without pressing enter and touch the Yubikey's button. The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.

You can display information about the login data generated by pam_yubico by adding the debug option to the auth line in/etc/pam.d/sshd. However, if you're using a central authorization file, you should remove that option once finished testing, as it causes pam_yubico to display the entire content of the central file to every user who logs in using a Yubikey.

Explanation

This works because the prompt is pam_yubico.so's one, since this module is before pam_unix.so, which normally does basic password authentication. So, you are giving a string that is the concatenation of your password and the OTP to pam_yubico.so. Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password. It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator pam_unix.so is instructed to try receiving a password from the previous module with try_first_pass, so it automatically uses the password sent by pam_yubico.so.