Yubikey

This article describes how you can integrate Yubico's YubiKey with NixOS.

GPG and SSH

services.udev.packages = [ pkgs.yubikey-personalization ];

programs.gnupg.agent = {
  enable = true;
  enableSSHSupport = true;
};

Logging-in

To use your yubikey as a user login or for sudo access you'll have to install a PAM (Pluggable Authentication Module) for your yubikey.

pam_u2f

The pam_u2f module implements the U2F (universal second factor) protocol. The protocol was initially developed by Yubico, Google and NXP and is nowadays hosted as an open-standard by the FIDO Alliance. All current and most legacy Yubikeys support the U2F protocol making this the preferred way to use Yubikeys for user login.

Use this page to check whether your Yubikey supports FIDO U2F before starting: https://www.yubico.com/products/identifying-your-yubikey/

1. Connect your Yubikey

2. Create an authorization mapping file for your user. The authorization mapping file is like ~/.ssh/known_hosts but for Yubikeys.

nix-shell -p pam_u2f
mkdir -p ~/.config/Yubico
pamu2fcfg > ~/.config/Yubico/u2f_keys
add another yubikey (optional): pamu2fcfg -n >> ~/.config/Yubico/u2f_keys

3. Verify that ~/.config/Yubico/u2f_keys contains one line in the following style:

<username>:<KeyHandle1>,<UserKey1>,<CoseType1>,<Options1>:<KeyHandle2>,<UserKey2>,<CoseType2>,<Options2>:...

4. Enable the u2f PAM module for login and sudo requests

security.pam.services = {
  login.u2fAuth = true;
  sudo.u2fAuth = true;
};

PAM U2F Docs: https://developers.yubico.com/pam-u2f/

5. Verify PAM configuration

See chapter Test PAM configuration an the end of this page.

yubico-pam

The yubico-pam module uses a OTP (one time password) challenge response to authenticate users.

Use this page to check whether your Yubikey supports Yubico OTP before starting: https://www.yubico.com/products/identifying-your-yubikey/

You'll first need to install the necessary udev packages to your NixOS configuration:

services.udev.packages = [ pkgs.yubikey-personalization ];

You can program the Yubikey for challenge-response on slot 2 and setup the current user for logon:

nix-shell -p yubico-pam -p yubikey-manager
ykman otp chalresp --touch --generate 2
ykpamcfg -2 -v

Finally, you can enable challenge-response logins with the following commands:

1.) run: nix-shell --command 'ykinfo -s' -p yubikey-personalization to get the serial code and enter it into yubico.id = [ "12345678" ];

Warning: Ignoring step 1 is considered insecure, any user could just plugin a yubikey and gain root access!

2.)

security.pam.yubico = {
   enable = true;
   debug = true;
   mode = "challenge-response";
   id = [ "12345678" ];
};

To automatically login, without having to touch the key, omit the --touch option.

Having that, you should be able to use your Yubikey to login and for sudo. You can also set security.pam.yubico.control to "required" in order to have multi-factor authentication.

Smartcard mode

To use the smart card mode (CCID) of Yubikey, you will need the PCSC-Lite daemon:

services.pcscd.enable = true;

Please note that the PCSC-Lite daemon sometimes conflicts with gpg-agent. This can be solved by putting the line disable-ccid into ~/.gnupg/scdaemon.conf. There is also a Home Manager Option for that.

OTP

In order to manage OTP keys, you should install the yubioath-flutter package in your profile. This application will also require both the udev rules as well as pcscd enabled.

Key generation

It is best practice to create the keys on a system without network connection to avoid leakages. This guide explains in depth the steps needed for that. There is also a nix expression that creates a nixos live image with all necessary dependencies pre-installed. The image can be created with the nixos-generator tool and depending on the image copied onto a usb stick or executed directly using kexec

Multiple keys

If you want to use GPG with multiple keys, containing the same subkeys, you have to do this routine when swapping the key

killall gpg-agent
rm -r ~/.gnupg/private-keys-v1.d/
Plug in the new YubiKey
gpg --card-status (optional, to see if key is visibile)

Test PAM configuration

Test user and/or sudo authentication. Replace <username> by your users account name.

nix-shell -p pamtester
pamtester login <username> authenticate
pamtester sudo <username> authenticate

If the result is pamtester: successfully authenticated then everything should work as expected.

Locking the screen when a Yubikey is unplugged

This can be achieved with a udev rule, which can be added to your configuration.nix

services.udev.extraRules = ''
      ACTION=="remove",\
       ENV{ID_BUS}=="usb",\
       ENV{ID_MODEL_ID}=="0407",\
       ENV{ID_VENDOR_ID}=="1050",\
       ENV{ID_VENDOR}=="Yubico",\
       RUN+="${pkgs.systemd}/bin/loginctl lock-sessions"
  '';

This will lock all sessions if any Yubikey matching the rule is unplugged.

If this does not work with your Yubikey take a look at the output of this command when you plug-in/unplug your Yubikey udevadm monitor --udev --environment and adjust the rule accordingly. This rule should work with most Yubikey 5 series models

Links