#yubikey #pam #singlefactor

YubiKey as a single factor PAM authentication

Yubikeys are a great tool to enhance your security while using your computer. But besides using their second factor they can do a lot more. Here are a few ways I am using my Yubikey.


My boss is somebody who values security really much. So it was just a matter of time before he tried convincing me to get one yubikey. The company behind these sticks, yubico, has quite a big portfolio. I first thought about buying the yubikey-neo since its NFC capabilities allow connecting it to a smart phone. Unfortunately since it is a generation 3 product it only supports 2048-bit PGP keys.

So I got the YubiKey 4 which is a generation 4 stick. Setting it up was really easy, just visit https:/yubico.com/start and it shows you a list of all providers which support the FIDO security keys. Adding your YubiKey to them is quite easy, at least if you use Google Chrome. Firefox has support for this (although it has to be enabled in the config) but most sites block the usage of the 2FA security tokens based on the user agent so it only works in on a few sites.

Besides using it for 2FA I have found the following use cases:

  • Saving my PGP key on it
  • Using it for local authentication

The first one is well documented but the latter is mostly focused on adding a second factor to the normal authentication.

Since I am quite sure that I won’t have the key with me all the time using 2FA for authentication is not a good idea. But it is possible to use the yubico_pam module to either have to type in the normal password or using the otp generated by the YubiKey. Since I did not find any information about this use case on the internet I build it myself through try and error.

Using the YubiKey as a One-Factor PAM Authentication method

The first step is to install the yubico PAM module. On Arch this is as simple as typing in

sudo pacman -S yubico-PAM

After doing this I recommend to open a separate root shell, best case on a tty. This is so you do not lock yourself out of your system while manipulating your pam config.

Keep that root shell in the background and edit your PAM config. It is located in /etc/pam.d/system-auth although you can limited the scope of the YubiKey authentication by editing one of the other files in the pam.d folder (for example the sudo file). The default system-auth file looks something like this:

#%PAM-1.0

auth      required  pam_unix.so     try_first_pass nullok
auth      optional  pam_permit.so
auth      required  pam_env.so

account   required  pam_unix.so
account   optional  pam_permit.so
account   required  pam_time.so

password  required  pam_unix.so     try_first_pass nullok sha512 shadow
password  optional  pam_permit.so

session   required  pam_limits.so
session   required  pam_unix.so
session   optional  pam_permit.so

Since it is important to understand the syntax of PAM files, here it is a short introduction.

Interlude: PAM-Files

The first word inside a line in your pam config is the management group of the rule. For example auth is used for authentication (by asking the user for credentials) and password rules are necessary for changes to user passwords. For example in the above config setting a new password calls the pam_unix module which is responsible for the normal password handling. If we wanted to add more security we could add the line password required pam_cracklib.so retry=3 minlen=6 difok=3 which uses the cracklib module to limit user passwords to certain requirements (retry=3: three tries to set a new password, minlen=6: at least six characters long, difok=3: at least three letters have to be different from the old password)

The second parameter describes the enforcing of this rule. Required means that this rule has to be executed successful or the whole run fails. There are a lot of keywords here like sufficient and optional. More information about these can be found in the man page of pam.conf.

The third part of a rule is the invoked module. After it there are only module specific options.

Adding the yubico module

Now comes the part which was the hardest and where I heavily depended on trial and error to get it right. Adding the PAM module needed some special parameters instead of the normal “one word” second parameter:

#%PAM-1.0

auth      sufficient  pam_unix.so     try_first_pass nullok
auth      [success=done new_authtok_reqd=ok ignore=ignore default=bad] pam_yubico.so  id=XXXXXX key=YYYYYY use_first_pass authfile=/etc/yubikey_mappings
#auth      optional  pam_permit.so
auth      required  pam_env.so

account   required  pam_unix.so
account   optional  pam_permit.so
account   required  pam_time.so

password  required  pam_unix.so     try_first_pass nullok sha512 shadow
password  optional  pam_permit.so

session   required  pam_limits.so
session   required  pam_unix.so
session   optional  pam_permit.so

The id and key can be obtained on the yubcico developer site. The only file necessary is the authfile, which maps a user to one or more YubiKeys with the following format.

username:yubikey_id

The id can be acquired by using the modhex website where the modhex encoded value is the id of the YubiKey. Multiple ids can be added to a user by appending them with a double colon.