From NixOS Wiki
Jump to: navigation, search

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


Based on a guide by @drduh:

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

# Depending on the details of your configuration, this section might be necessary or not;
# feel free to experiment
environment.shellInit = ''
  export GPG_TTY="$(tty)"
  gpg-connect-agent /bye
  export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"

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

If you don't have a graphical user interface, you'll have to adjust the pinentry program (it's the program launched by operating system to ask for YubiKey's PIN):

programs.gnupg.agent.pinentryFlavor = "curses";


You can enable challenge-response logins with:

security.pam.yubico = {
   enable = true;
   debug = true;
   mode = "challenge-response";

You'll also need to program the Yubikey for challenge-response on slot 2 and setup the current user for logon:

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

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.

See also: https://developers.yubico.com/yubico-pam/Authentication_Using_Challenge-Response.html.

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.


In order to manage OTP keys, you should install the yubioath-desktop 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

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