Introduction

The purpose of this document is to guide readers through the configuration steps to use two factor authentication for SSH using Yubikey. This document assumes that the reader has advanced knowledge and experience in Linux system administration, particularly for how PAM authentication mechanism is configured on a Linux platform.

Prerequisites

Successful configuration of the Yubico PAM module to support two factor authentication requires following prerequisites:

Operating System

Any Unix operating system which supports PAM (Pluggable Authentication Module)

Complier

GNU GCC complier

Yubico Client C library

Version 1.5 or later

Yubico PAM Module

Version 1.7 or later

System Requirements

This document illustrates the configuration steps for Fedora Core 8 operating system. However, there steps should work on most other Linux distributions.

The Yubico PAM module for SSH can be downloaded from here.

The Yubico PAM module support two factor authentication for SSH. The two factor authentication module verifies the user name and password for the user and the One-Time Password (OTP) generated by Yubikey assigned to the user.

Build yubico-c-client and pam_yubico

Build instructions for yubico-c-client and pam_yubico are found in their respective README.

Configuration

Configuration for user and YubiKey token ID mapping

There are two ways of user and YubiKey token ID mapping. It can be either done at administrative level or at individual user level.

Administrative Level

In Administrative level, system administrators hold right to configure the user and yubikey token ID mapping. Administrators can achieve this by creating a new file that contains information about the username and the corresponding IDs of Yubikey(s) assigned.

This file contains user name that is allowed to connect to the system over SSH and the token id of the Yubikey(s) assigned to that particular user. A user can be assigned multiple Yubikeys and this multi key mapping is supported by this file. However, presently there is no logic coded to detect or prevent use of same Yubikey ID for multiple users.

Each record in the file should begin on a new line. The parameters in each record are separated by : character similar to /etc/passwd.

The contents of this file are as follows:

<user name>:<yubikey token ID>:<yubikey token ID>: ….
<user name>:<yubikey token ID>:<yubikey token ID>:…..

e.g.

paul:indvnvlcbdre:ldvglinuddek
simon:uturrufnjder:hjturefjtehv
kurt:ertbhunjimko

The mapping file must be created/updated manually before configuration of Yubico PAM module for SSH authentication.

Configuration of modified pam_yubico.so module at administrative level

Append the following line to the beginning of the /etc/pam.d/sshd file:

auth required pam_yubico.so id=16 debug authfile=/path/to/mapping/file

Make sure you set id=16 to the correct API-id for the yubico validation server.

After the above configuration changes, whenever a user connects to the server using any ssh client, the PAM authentication interface will pass the control to Yubico PAM module. The Yubico PAM module first checks the presence of authfile argument in PAM configuration. If authfile argument is present, it parses the corresponding mapping file and verifies the username with corresponding Yubikey token id as configured in the mapping file. If valid, the Yubico PAM module extracts the OTP string and sends it to the Yubico authentication server or else it reports failure. If authfile argument is present but the mapping file is not present at the provided path PAM module reports failure. After successful verification of OTP Yubico PAM module from the Yubico authentication server, a success code is returned.

User Level

In User level, individual users have the ability to configure yubikey token ID assigned to them. Users can achieve this by creating a new file .yubico/authorized_yubikeys inside their home directories that contains information about the username and the corresponding IDs of Yubikey(s) assigned to them. A user can be assigned multiple Yubikeys and the multi key mapping is supported by this file.

This file must contain only one record. The parameters in the record are separated by : character similar to /etc/passwd. The contents of this file are as shown below:

<user name>:<yubikey token ID>:<yubikey token ID>: ….

e.g.

paul:indvnvlcbdre:ldvglinuddek

The .yubico/authorized_yubikeys file must be created/updated manually and must be placed inside user’s home directory before configuration of Yubico PAM module for SSH authentication.

Configuration of modified pam_yubico.so module at user level

Append the following line to the beginning of the /etc/pam.d/sshd file:

auth required pam_yubico.so id=16 debug

After the above configuration changes, whenever a user connects to the server using any SSH client, the PAM authentication interface will pass the control to Yubico PAM module. The Yubico PAM module first verifies the username with corresponding Yubikey token id as configured in the .yubico/authorized_yubikeys file that present in the user’s home directory who is trying to assess server through SSH. If valid, the Yubico PAM module extracts the OTP string and sends it to the Yubico authentication server or else it reports failure. After successful verification of OTP Yubico PAM module from the Yubico authentication server, a success code is returned.

pam_unix.so configuration

Append try_first_pass parameter to the pam_unix.so module to authenticate the user with password passed from the preceding auth module.

The pam_unix.so module used for authentication is generally located into /etc/pam.d/system-auth for RedHat based Linux system and into /etc/pam.d/common-auth for Debian based Linux systems.

SSH configuration

Edit the sshd configuration file /etc/ssh/sshd_config`_ to disable challenge- response passwords. Change `challenge-response passwords yes to challenge-response passwords no.

Test Setup

Fedora 8

Test setup for fedora 8 environment is as follows:

OS Version

Fedora release 8 (Werewolf)

Kernel Version

Kernel version 2.6.23.1-42.fc8

OpenSSH Version

openssh-4.7p1-2.fc8

Yubico PAM Version

pam_yubico-1.7

Fedora 6

Test setup for fedora 6 environment is as follows:

OS Version

Fedora Core release 6 (Zod)

Kernel Version

Kernel version 2.6.18-1.2798.fc6

OpenSSH Version

openssh-4.3p2-10

Yubico PAM Version

pam_yubico-1.7

PAM configuration

PAM configuration files in our testing environment are as follows:

/etc/pam.d/sshd

auth           required          pam_yubico.so authfile=/etc/yubikeyid id=16 debug
auth           include           system-auth
account        required          pam_nologin.so
account        include           system-auth
password       include           system-auth
session        optional          pam_keyinit.so force revoke
session        include           system-auth
session        required          pam_loginuid.so

/etc/yubikeyid

root:indvnvlcbdre:ldvglinuddek
test:ldvglinuddek
/root/.yubico/authorized_yubikeys
root:indvnvlcbdre:ldvglinuddek

Please change PAM configuration settings for SSH as shown above and test the configuration.

Testing the Configuration

We assume that you have root and test user configured to access SSH on your test environment with password secret and pencil respectively.

Use any standard SSH client for testing (We used SSH command line utility).

Try to login to server with SSH client as configured user:

ssh -l test localhost
Password: (enter 'pencil' and touch the ldvglinuddek yubikey)
ssh -l root localhost
Password: (enter 'secret' and touch the ldvglinuddek yubikey)
ssh -l root localhost
Password: (enter 'secret' and touch the indvnvlcbdre yubikey)