YubiKey/PAM

Resources

Many YubiKeys can be configured to provide FIDO/U2F authentication. This can be configured with the pam_u2f.so module in PAM.

Introduction

YubiKeys provide several interfaces which can be used to authentication or encryption. The U2F/FIDO module can be used to provide authentication for both SSH and PAM, and is commonly used with web services.

PAM is used to provide centralized authentication on Linux systems, using pluggable modules. It is typically used as the backend for TTY authentication as well as most local services which require authentication, such as the login manager, screensavers/lockscreens, and privilege escalation tools such as doas or sudo. Using PAM control directives, the required authentication factors can be adjusted depending on what type of service is attempting authentication.

When a username and password are used for authentication, PAM typically uses a combination of the /etc/passwd and /etc/shadow files to map users to their passwords. In order to use a YubiKey with PAM, a file which maps users to their YubiKeys is needed. This can be a central file such as /etc/u2f_mappings or a per-user file such as ~/.config/Yubico/u2f_keys.

Installation

Kernel

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

KERNEL Enable support for raw HID devices

Device Drivers  --->
  HID support  --->
    -*- HID bus support
    [*]   /dev/hidraw raw HID device support
    USB HID support  --->
      [*] /dev/hiddev raw HID device support

USE flags

USE flags for sys-auth/pam_u2f PAM module for FIDO2 and U2F keys

debug Enable debug messages using the pam logging macros.

Data provided by the Gentoo Package Database · Last update: 2024-09-24 05:49 More information about USE flags

Emerge

PAM, is modular by design, and adding modules is straightforward. sys-auth/pam_u2f ^[1] is required to use a YubiKey with PAM. This package provides the PAM module as well as tools to assist in the confutation of this module.

root #emerge --ask sys-auth/pam_u2f

Configuration

plugdev group

When udev is being used, /lib/udev/rules.d/70-libfido2-u2f.rules defines rules that change the ownership of the YubiKey or other fido2/U2F compliant device's associated /dev/hidraw{n} to be owned by the plugdev group with the 0660 mode. In order for non-root users to access this, which is required to use pamu2fcfg, users must be added to the plugdev group.

To check the current user's groups, run:

user $

groups

tty wheel audio video kvm users user

If plugdev is not listed, the user can be added to the group by running:

root #

usermod -a -G plugdev user

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

Important
Users don't need to be member of the plugdev group to be able to login with a YubiKey!

Mapping user-tokens

In order to authenticate with PAM using pam_u2f, a key token must be mapped to a user - unless the nouserok module argument is specified. By default, these mappings are read from ~/.config/Yubico/u2f_keys.

Note
A central mapping file such as /etc/u2f_mappings can be configured using the authfile module argument.

Creating user-token mapping (per-user file)

To create a per-user mapping, insert the YubiKey and run pamu2fcfg to create a u2f key mapping for the current user:

user $

mkdir -p ~/.config/Yubico

user $

pamu2fcfg > ~/.config/Yubico/u2f_keys

Enter the u2f pin and tap the presence detection pad once it starts blinking.

Tip
The -u parameter can be used with pamu2fcfg to specify the user.

Mapping additional keys

To map an additional key to the current user, replace the YubiKey with the next one and run:

user $

pamu2fcfg -n >> ~/.config/Yubico/u2f_keys

Touch the YubiKey when it starts blinking.

Important
Ensure there is no newline at the end of the file, all key values should be on the first line.

Creating user-token mapping (central file)

Warning
Any user that can edit the central mapping file can control the authentication of other users. Ensure that this file is writable only by root or other administrative accounts.

To create a central mapping file, insert the YubiKey and run (replacing user with the appropriate username):

root #

pamu2fcfg -uuser >> /etc/u2f_mappings

Touch the YubiKey when it starts blinking.

Mapping additional keys

A little more care is needed when mapping an additional key to a user if a central file is used. It is possible to directly concatenate the output of pamu2fcfg if a second mapping is created right after the first one. Each user is represented by a single line with colon-delimited entries corresponding to a YubiKey:

FILE /etc/u2f_mappingsFormat of the YubiKey mapping file

# <user name>:<keyHandle1>,<public_key1>:<keyHandle2>,<public_key2>:...
paul:aaaa...,bbbb...:cccc...,dddd...
simon:eeee...,ffff...:gggg...,hhhh...
kurt:iiii...,jjjj...

Manually copy/pasting the output of the following command onto the end of the relevant user's line in the mapping file is recommended in order to maintain its integrity:

root #

pamu2fcfg -n

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

PAM U2F

Global system authentication is configured through /etc/pam.d/system-auth. Taking a backup of the current PAM configuration will make it easy to revert changes if needed.

Warning
A broken PAM configuration can result in every user (including root) being locked out of the system. Leaving a spare root login open (such as in a TTY) while editing the configuration files will save having to boot from a live USB or through single-user mode to fix PAM.

Note
Additional configuration may be needed for successful authentication over SSH if both password and YubiKey are required.

PAM options

While configuring PAM service files in /etc/pam.d/ to work with a YubiKey or other U2F compliant device, several options can be used:

Option	Type	Description
`required`	control value	The given PAM module must succeed in order for the entire `management group type` (such as auth) to succeed. If the PAM module fails, other PAM modules are still executed (even though it is already certain that the service itself will be denied).
`sufficient`	control value	If the given PAM module succeeds, authentication succeeds and the other PAM modules are not executed. If the PAM module fails, then the failure is ignored and PAM continues with the next module.
`[value1=action1 value2=action2 ...]`	control values	Advanced combinations using one or many values, validating the return code of the value against the respective action, can be used instead of standard control values.
`nouserok`	module argument	Specific to the pam_u2f.so module, allowing for successful authentication in the event that the user is missing an authorization mapping or it is invalid. Without this, any users missing a mapping will fail authentication.
`cue`	module argument	Specific to the pam_u2f.so module, prompts Please touch the device. when attempting authentication. If not set, the YubiKey will flash as a prompt, but there may be no on-screen indication.
`authfile=/etc/u2f_mappings`	module argument	Specific to the pam_u2f.so module, sets the path for a central mapping file. If this is not set, ~/.config/Yubico/u2f_keys is used by default.

Tip
A complete list of options for pam_u2f.so is available here.

Testing PAM with a YubiKey

In order to test that everything works, temporarily configure PAM to use a YubiKey without locking the user out if pam_u2f fails by adding the following line to the top of /etc/pam.d/system-auth: