1. YubiPAM Introduction

The YubiPAM module provides a simple, easy to configure, way to integrate the Yubikey into your existing user authentication infrastructure. PAM is used by GNU/Linux, Solaris and Mac OS X for user authentication.

2. Status

1. Manual add/delete from database. Using the ykpasswd tool you can add delete yubikey entries from the database (default: /etc/yubikey).

2. Per user accounting. Supports individual user account authorisation. Every user may have multiple Yubikey dongles only make sure you are using different public UID's on every Yubikey dongle.

3. Single and second factor sign in. Next to single factor ie. Yubikey OTP you can define an additional passcode. The pam module will detect if the second factor passcode is needed.

4. Static heuristic support. Heuristic support for OTP data deltas is hard coded. This will be changable in the next release.

3. Build

Build the YubiPAM module by using autotools. First generate the configure file $ autoreconf -i

You should run the configure file which will generate the Makefile. Run make to build the YubiPAM module. $ ./configure $ make $ sudo make install $ sudo addgroup yubiauth $ sudo touch /etc/yubikey $ sudo chgrp yubiauth /etc/yubikey /usr/local/sbin/yk_chkpwd $ sudo chmod g+rw /etc/yubikey $ sudo chmod g+s /usr/local/sbin/yk_chkpwd

4. Configuration

Install it in your PAM setup by adding a line to an appropriate file in the director /etc/pam.d/:

auth sufficient pam_yubikey.so

and ensure pam_yubikey.so is located in /lib/security/

Supported PAM module parameters are:

debug enable debug.

verbose_otp enable echoing of the OTP, after all it's only a one time pad.

include_users enable yubikey auth for users in the given file. Eash line can contain one user. Ex: include_users=/etc/yubikey.users

exclude_users disable yubikey auth for users in the given file. Eash line can contain one user. Ex: exclude_users=/etc/yubikey.users

no_passcode instructs the module to not save the pam authtok to allow for two-factor authentication with other pam modules such as pam_ecryptfs which is configured to use the user's passphrase.

passcode_only instead of the OTP, pam authtok will only contain the passcode. This can be very handy when you are using other pam modules like pam_ecryptfs.

combined_passcode_otp allows user to enter passcode+OTP on a single prompt line. Useful for services that don't work with multiple prompt two-factor auth (e.g. certain screensavers, X display managers) The passcode and OTP must be separated with a single | character

discreet_prompt emulate the default Unix password prompt, to avoid indicating a Yubikey is to be used

Most keyboard layouts will work out of the box, as Yubico designed the keypresses used by the Yubikey to be the same on many layouts (qwerty, azerty, etc). Some layouts, however, such as Dvorak and Colemak do not share the same character mapping. English Dvorak and Colemak will work out of the box for authentication, as will any other keymaps you add.

However, when using ykpasswd with a keymap other than one compatible with standard modhex, you must ensure that the OTP given to -o is in modhex (this is to ensure you enroll the key that you meant to.)

Thus, you should either temporarily switch your keyboard layout to qwerty before running ykpasswd to enroll users, or use the provided layout conversion script contrib/convert-modhex-to-keymap.py to convert from your layout of choice to modhex.

To add support for additional keymaps, edit utils/yk_chkpwd.c and add your keymap(s) of choice to the KEYMAPS array.

5. Utilities

ykpasswd

The ykpasswd utility provides administration, insert and removal of entries, for the YubiPAM database. The required elements that need to be entered into the database include the public UID (fixed modhex portion of an OTP), the AES key which can be used to decrypt the token, and the private UID which is found after successful decryption of a valid OTP.

If you have apriori knowledge of these values for user joesmith you can enter them straight into the command line, using:

ykpasswd -a -k AESKEY -f PUBLICKEY -p PRIVATEKEY -u joesmith

Or alteratnively you can just enter the minimum and be prompted to enter the information using:

ykpasswd -a -u joesmith

If you don't have the private UID it requires you to decrypt a valid token to get the value. Fortunately you can provide a valid OTP and the appropriate AES key and let ykpasswd determine the public and private UIDs for you, using:

ykpasswd -a -u joesmith -k AESKEY -o OTP

The "-u" option is mandatory and should always be defined.

ykvalidate

Once a Yubikey has been successfully added to the YubiPAM database, it can be tested using the ykvalidate tool. Simply pass an OTP associated with the calling user or specify the actual user and it will confirm if it's VALID or NOT.

ykvalidate OTP

ykvalidate -u joesmith OTP

6. Troubleshooting

In the event that the YubiPAM module is not working it may pay to enable debug mode in order to sort out any issues. To enable debug mode just add the PAM module parameter "debug" to your PAM entry:

auth sufficient pam_yubikey.so debug

Note: On production systems, debug should NOT be turned on due to its verbosity and subsequent disclosure of information.