YubiKey/PAM

This page goes over Article description::authenticating with [[PAM using a YubiKey.]]

Emerge
The main component is a PAM module called. The package also contains a tool called which is used to generate the required authorization mappings.

Kernel
Support for raw USB HID devices is required in the kernel for the YubiKey to function.

plugdev
For a non-root user to be able to access the YubiKey, they need to be a member of the group. To check if the current user is in the group, run:

If is not listed, add the user to the group by running:

The user needs to log out and log back in for the group membership to take effect.

Creating an authorization mapping
In order to authenticate with PAM using, a key token needs to be mapped to a user. By default, these mappings are stored in. To create a mapping, insert the YubiKey and run:

Touch the YubiKey when it starts blinking.

Mapping additional keys
To map additional keys to a user, remove the currently inserted YubiKey (if any) and insert the next one. Then run:

Touch the YubiKey when it starts blinking. Repeat for any remaining YubiKeys.

Configuring PAM
Global system authentication is configured through. Taking a backup of the current PAM configuration will make it easy to revert back if needed.

Requiring a password and YubiKey
To require both a password and a YubiKey to authenticate with PAM, modify the file to include the following:

means PAM will skip over one module if the current one succeeds. In this case it will jump to the module if the correct password is given. means the module will succeed if the authenticating user doesn't have an authorization mapping. Without this, any users that don't have a mapping configured will be locked out. means the user is prompted to touch the YubiKey during authentication. Without this, no prompt is given.

Requiring a password or YubiKey
To require either a password or a YubiKey to authenticate with PAM (but preferring the YubiKey), modify the file to include the following:

means PAM will consider the authentication to be successful if this module succeeds. Otherwise it goes to the next module. is not included because otherwise will succeed for users without a mapping configured. This would result in successful authentication without prompting for a password.

Troubleshooting
If no user is able to authenticate after completing the above, then a broken PAM configuration is the likely culprit. Even if no active root login is available, the system can still be fixed and authentication mechanisms restored by either live booting or booting into single-user mode.

Fixing PAM through single-user mode
To enter single-user mode first reboot the machine. When the GRUB menu appears, press E to bring up the boot entry editor. Any edits made in here are only temporary and do not edit the on-disk GRUB configuration. Locate the line which loads the kernel and append init=/bin/sh to the end of it. The actual number of kernel command line arguments is likely to differ from system to system, but the end result should look similar to the following:

Press F10 to boot using the present command list. Once an sh prompt appears, the root filesystem will need to be re-mounted as read/write:

Only specifying / will instruct mount to read the entries in /etc/fstab to find the correct block device as well as applying the mount options specified therein. Next, either restore the backup PAM configuration or manually edit /etc/pam.d/system-auth to undo any changes. To non-destructively undo changes, comment out the lines by prepending a # (and adding any new lines if needed).

Once done, commit the changes to disk, re-mount the root filesystem as read-only, and exit:

This will not be a clean exit and the kernel will panic with the message Kernel panic - not syncing: Attempted to kill init! This is fine because all the filesystem changes were manually synced beforehand. Finally, reboot the system. Authentication should be fully restored.

External resources

 * (Link to external resources [outside the Wiki] using bullet points in this section. It is common for the information in this section to be full sentences that are links.)