YubiKey
This page describes how to setup a YubiKey for authenticating with PAM.
Introduction
PAM is the central authentication service that is used when logging in through a TTY, a login manager, a screensaver application, and sometimes when over ssh. It is also used by privilege escalation programs such as doas and sudo. PAM can be configured to use a YubiKey to complement, or even replace, traditional password-based 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.
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. |
Emerge
PAM has a modular architecture, and the pam-u2f module is needed to enable it to interact with a YubiKey. This module reads the mapping file(s) to determine whether a user's authentication with a given YubiKey is successful.
root #emerge --ask sys-auth/pam_u2fThe package also contains a tool called pamu2fcfg which is used to generate the required mappings.
Configuration
plugdev
In case non-root users need to be able to use the pamu2fcfg tool used to setup the mappings, allow them access to the YubiKey by adding them to the plugdev group. To check if the current user is in the group, run:
user $groups
tty wheel audio video kvm users user
If plugdev is not listed, add the user 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.
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 needs to be mapped to a user. By default, these mappings are stored in ~/.config/Yubico/u2f_keys. Alternatively, a central mapping file such as /etc/u2f_mappings can be configured.
Creating user-token mapping (per-user file)
To create a per-user mapping, insert the YubiKey and run (replacing user with the appropriate username):
user $mkdir -p ~/.config/Yubico
user $pamu2fcfg -uuser > ~/.config/Yubico/u2f_keys
Touch the YubiKey when it starts blinking.
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.
Creating user-token mapping (central file)
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:
/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
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.
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.
Additional configuration may be needed for successful authentication over SSH if both password and YubiKey are required.
PAM options
While configuring /etc/pam.d/system-auth, several options will be used:
| Option | Type | Description |
|---|---|---|
required
|
control directive | The given PAM module must succeed in order for the entire service (such as authentication) 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 directive | 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. |
[value=action ...]
|
control directive | Allows finer-grained control based on the return value of the given PAM module. |
nouserok
|
module argument | This means the pam-u2f module will succeed if the authenticating user doesn't have an authorization mapping. Without this, any users that don't have a mapping configured may be locked out. |
cue
|
module argument | This means the user is prompted to touch the YubiKey during authentication. Without this, no prompt is given. |
authfile=/etc/u2f_mappings
|
module argument | This means a central mapping file must be used to look up the user belonging to a YubiKey. Without this, ~/.config/Yubico/u2f_keys is used. |
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:
/etc/pam.d/system-authauth sufficient pam_u2f.so cue
Attempting to log in as a user with a YubiKey mapped should now prompt for it. Providing a correct YubiKey should result in a successful login.
The following examples assume a per-user mapping file is used. If instead a central mapping file is used, it must be included in the PAM configuration:
/etc/pam.d/system-authauth sufficient pam_u2f.so cue authfile=/etc/u2f_mappings
Modifying the examples appropriately is left as an exercise to the reader.
Requiring a YubiKey
To require a YubiKey to authenticate with PAM, replace sufficient with required:
/etc/pam.d/system-authauth required pam_u2f.so cue
Requiring a password and a YubiKey
To require both a password and a YubiKey to authenticate with PAM, modify the file to include the following:
/etc/pam.d/system-authauth [success=1 default=ignore] pam_unix.so nullok try_first_pass auth [default=die] pam_faillock.so authfail auth required pam_u2f.so nouserok cue
success=1 means PAM will skip over one module if the current one succeeds. In this case it will jump to the pam-u2f module if the correct password is given.
nouserok is included here so that users without a mapping configured are able to authenticate as well. Leave this out to require all users to provide both a password and a YubiKey.
Requiring a password or a YubiKey
To require either a password or a YubiKey to authenticate with PAM (but preferring the YubiKey), modify the file to include the following:
/etc/pam.d/system-authauth sufficient pam_u2f.so cue auth [success=1 default=ignore] pam_unix.so nullok try_first_pass auth [default=die] pam_faillock.so authfail
nouserok is not included here because it would result in successful authentication without prompting for a password from users without a mapping configured.
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 live boot
These instructions assume a bootable medium with a live ISO, such as a USB, is already created and ready.
Once the filesystem is mounted, make sure to prefix all paths with /mnt to edit the on-disk configurations and not the live ISO's temporary files.
First, completely power off the machine. Insert the bootable medium and boot from it through the machine's firmware boot menu. There are no universal instructions since this process can vary greatly from machine to machine, so consult the relevant documentation if unfamiliar with how to do this.
Open up a root shell when booted, locate the block device corresponding to your root filesystem, and mount it (making sure to specify any required mount options):
root #fdisk -l
root #mount [-o options] device /mnt
Next, either restore a backup PAM configuration or manually edit /mnt/etc/pam.d/system-auth to undo any changes. To non-destructively undo changes, comment out the necessary entries by prepending a # and add any new entries if needed.
Once done, commit the changes to disk, unmount your root filesystem, and reboot:
root #sync
root #umount /mnt
root #reboot
Authentication should be fully restored.
Once successful authentication is confirmed, SELinux users must re-label their filesystem as described here.
Fixing PAM through single-user mode
These instructions assume the machine uses GRUB as the bootloader. Additionally, these instructions assume GRUB doesn't directly load and boot the kernel without displaying the GRUB menu. If another bootloader is used, consult the respective documentation for instructions on achieving a similar result. Alternatively, use the live boot method above.
To enter single-user mode first reboot the machine. When the GRUB menu appears, press E to bring up the menu entry editor. Any edits made in here are temporary and do not edit the on-disk GRUB configuration.
Locate the line which loads the kernel and append init=/bin/sh to it. The actual content and number of kernel command line arguments is likely to differ from system to system, but the end result should look similar to the following:
linux /vmlinuz-5.4.80-gentoo-r1 root=[omitted] ro init=/bin/sh
Press F10 to boot using the present command list.
Once the sh prompt appears, the root filesystem will need to be re-mounted as read/write:
sh#mount -o remount,rw /
Only specifying / will instruct mount to read the entries in /etc/fstab to find the correct block device and to apply the mount options specified therein.
Next, either restore a backup PAM configuration or manually edit /etc/pam.d/system-auth to undo any changes. To non-destructively undo changes, comment out the necessary entries by prepending a # and add any new entries if needed.
PATH will not be set to the usual value, so specifying the full path to an editor may be necessary if manually editing the PAM configuration. If the location of the desired editor is not known, a standard location to check for installed programs is /usr/bin.
Once done, commit the changes to disk, re-mount the root filesystem as read-only, and exit:
sh#sync
sh#mount -o remount,ro /
sh#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 sync-ed.
Finally, reboot the system. Authentication should be fully restored.
Supported devices
The following tables list all the YubiKey devices and their U2F support as stated on the Yubico website.
YubiKey 5 Series
| Device | Supports U2F [1] |
|---|---|
| YubiKey 5C NFC | Yes |
| YubiKey 5Ci | Yes |
| YubiKey 5 Nano | Yes |
| YubiKey 5C Nano | Yes |
| YubiKey 5 NFC | Yes |
| YubiKey 5C | Yes |
Security Key Series
| Device | Supports U2F [1] |
|---|---|
| Security Key NFC | Yes |
| FIDO U2F Security Key | Yes |
| Security Key by Yubico | Yes |
YubiKey FIPS Series
| Device | Supports U2F [1] |
|---|---|
| YubiKey Nano FIPS | Yes |
| YubiKey FIPS | Yes |
| YubiKey C Nano FIPS | Yes |
| YubiKey C FIPS | Yes |
YubiKey 4 Series
| Device | Supports U2F [1] |
|---|---|
| YubiKey 4C Nano | Yes |
| YubiKey 4 | Yes |
| YubiKey 4C | Yes |
| YubiKey 4 Nano | Yes |
Legacy Devices
| Device | Supports U2F [1] |
|---|---|
| YubiKey Nano | No |
| YubiKey Standard | No |
| YubiKey Edge-n | Yes |
| YubiKey NEO-n | Yes |
| YubiKey Edge | Yes |
| YubiKey NEO | Yes |
YubiHSM Series
| Device | Supports U2F [1] |
|---|---|
| YubiHSM 1 | No |
| YubiHSM 2 | No |
See also
- PAM — allows (third party) services to provide an authentication module for their service which can then be used on PAM enabled systems.
- PAM securetty — restricting root authentication with PAM.
- Google Authenticator — describes an easy way to setup two-factor authentication on Gentoo.
External resources
- pam.conf(5), the man page describing PAM configuration files.
References
- ↑ 1.0 1.1 1.2 1.3 1.4 1.5 Yubico devices. Archived from the original.