YubiKey

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

Installation

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.
libressl Use dev-libs/libressl instead of dev-libs/openssl when applicable (see also the ssl useflag)
Data provided by the Gentoo Package Database · Last update: 2021-03-06 06:03 More information about USE flags

Emerge

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

root #emerge --ask sys-auth/pam_u2f

Pre-requisites

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

plugdev

For a non-root user to be able to access the YubiKey, they need to be a member of 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.

Configuration

Creating an authorization mapping

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. To create a mapping, insert the YubiKey and run:

user $mkdir -p ~/.config/Yubico
user $pamu2fcfg -uuser > ~/.config/Yubico/u2f_keys

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:

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

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

Configuring 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.

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.

Requiring a password and YubiKey

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

FILE /etc/pam.d/system-auth
auth        [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 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 will be locked out. cue 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:

FILE /etc/pam.d/system-auth
auth        sufficient                  pam_u2f.so      cue
auth        [success=1 default=ignore]  pam_unix.so     nullok try_first_pass
auth        [default=die]               pam_faillock.so authfail

sufficient means PAM will consider the authentication to be successful if this module succeeds. Otherwise it goes to the next module. nouserok is not included because otherwise pam-u2f 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 live boot

Note
These instructions assume a bootable medium with a live ISO, such as a USB, is already created and ready.
Important
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.

Important
Once successful authentication is confirmed, SELinux users must re-label their filesystem as described here.

Fixing PAM through single-user mode

Note
These instructions assume the machine uses GRUB2 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:

CODE GRUB menu entry snippet
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.

Important
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. 1 2 3 4 5 6 Yubico devices. Archived from the original.
This article is issued from Gentoo. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.