Repository files navigation

yubikey-agent is a seamless ssh-agent for YubiKeys.

• Easy to use. A one-command setup, one environment variable, and it just runs in the background.
• Indestructible. Tolerates unplugging, sleep, and suspend. Never needs restarting.
• Compatible. Provides a public key that works with all services and servers.
• Secure. The key is generated on the YubiKey and can't be extracted. Every session requires the PIN, every login requires a touch. Setup takes care of PUK and management key.

Written in pure Go, it's based ongithub.com/go-piv/piv-go andgolang.org/x/crypto/ssh.

brew install yubikey-agentbrew services start yubikey-agentyubikey-agent -setup # generate a new key on the YubiKey

Then add the following line to your~/.zshrc and restart the shell.

export SSH_AUTH_SOCK="$(brew --prefix)/var/run/yubikey-agent.sock"

On Arch, usetheyubikey-agent package from the AUR.

git clone https://aur.archlinux.org/yubikey-agent.gitcd yubikey-agent && makepkg -sisystemctl daemon-reload --usersudo systemctl enable --now pcscd.socketsystemctl --user enable --now yubikey-agentexport SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/yubikey-agent/yubikey-agent.sock"

On NixOS unstable and 20.09 (unreleased at time of writing), you canadd this to your/etc/nixos/configuration.nix:

services.yubikey-agent.enable = true;

This installsyubikey-agent and sets up a systemd unit to startyubikey-agent for you.

On other systems using nix, you can also install from nixpkgs:

nix-env -iA nixpkgs.yubikey-agent

This installs the software but doesnot install a systemd unit. Youwill have to set up service management manually (see below).

On other systemd-based Linux systems, followthe manual installation instructions.

Packaging contributions are very welcome.

Install theyubikey-agent port.

Windows support is currently WIP.

It's possible to configuressh-agents on a per-host basis.

For example to only useyubikey-agent when connecting toexample.com, you'd add the following lines to~/.ssh/config instead of settingSSH_AUTH_SOCK.

Host example.com    IdentityAgent /usr/local/var/run/yubikey-agent.sock

To useyubikey-agent for all hosts but one, you'd add the following lines instead. In both cases, you can keep usingssh-add to interact with the mainssh-agent.

Host example.com    IdentityAgent $SSH_AUTH_SOCKHost *    IdentityAgent /usr/local/var/run/yubikey-agent.sock

yubikey-agent takes a persistent transaction so the YubiKey will cache the PIN after first use. Unfortunately, this makes the YubiKey PIV and PGP applets unavailable to any other applications, likegpg-agent and Yubikey Manager. Our upstreamis investigating solutions to this annoyance.

If you needyubikey-agent to release its lock on the YubiKey, send it a hangup signal. Likewise, you might have to killgpg-agent after use for it to release its own lock.

killall -HUP yubikey-agent

This does not affect the FIDO2 functionality.

Use YubiKey Manager to change the PIN and PUK.

yubikey-agent -setup sets the PUK to the same value as the PIN.

killall -HUP yubikey-agentykman piv access change-pinykman piv access change-puk

If the wrong PIN is entered incorrectly three times in a row, YubiKey Manager can be used to unlock it.

yubikey-agent -setup sets the PUK to the same value as the PIN.

ykman piv unblock-pin

If the PUK is also entered incorrectly three times, the key is permanently irrecoverable. The YubiKey PIV applet can be reset withyubikey-agent --setup --really-delete-all-piv-keys.

yubikey-agent only officially supports YubiKeys set up withyubikey-agent -setup.

In practice, any PIV token with an RSA or ECDSA P-256 key and certificate in the Authentication slot should work, with any PIN and touch policy. Simply skip the setup step and usessh-add -L to view the public key.

yubikey-agent -setup generates a random Management Key andstores it in PIN-protected metadata.

Recent versions of OpenSSHsupport using FIDO2 tokens directly. Since those are their own key type, they require server-side support, which has only recently reached Debian andGitHub.

FIDO2 SSH keys by default don't require a PIN, and require a private key file, acting more like a second factor.yubikey-agent keys always require PINs and can be ported to a different machine simply by plugging in the YubiKey. (With recent enough tokens such as a YubiKey 5, a similar setup can be achieved by using theverify-required andresident options, after setting a FIDO2 PIN with YubiKey Manager: the private key file will still be required, but it can be regenerated from the YubiKey.)

gpg-agent can act as anssh-agent, and it can use keys stored on the PGP applet of a YubiKey.

This requires a finicky setup process dealing with PGP keys and thegpg UX, and seems to lose track of the YubiKey and require restarting all the time. Frankly, I've also had enough of PGP and GnuPG.

ssh-agent can load PKCS#11 applets to interact with PIV tokens directly. There are two third-party PKCS#11 providers for YubiKeys (OpenSC and ykcs11) and one that ships with macOS (man 8 ssh-keychain).

The UX of this solution is poor: it requires callingssh-add to load the PKCS#11 module and to unlock it with the PIN (as the agent has no way of requesting input from the client during use, a limitation thatyubikey-agent handles withpinentry), and needs manual reloading every time the YubiKey is unplugged or the machine goes to sleep.

The ssh-agent that ships with macOS (which is pretty cool, as it starts on demand and is preconfigured in the environment) also has restrictions on where the.so modules can be loaded from. It can see through symlinks, so a Homebrew-installed/usr/local/lib/libykcs11.dylib won't work, while a hard copy at/usr/local/lib/libykcs11.copy.dylib will.

/usr/lib/ssh-keychain.dylib works out of the box, but only with RSA keys. Key generation is undocumented.

Secretive andSeKey are similar projects that use the Secure Enclave to store the private key and Touch ID for authorization. The Secure Enclave has so far a worse security track record compared to YubiKeys.

pivy-agent is part of a suite of tools to work with PIV tokens. It's similar toyubikey-agent, and inspired its design.

The main difference is that it requires unlocking viassh-add -X rather than using a graphical pinentry, and it caches the PIN in memory rather than relying on the device PIN policy. It's also written in C.

yubikey-agent also aims to provide an even smoother setup process.