Awesome

PIV Agent

About

piv-agent is an SSH and GPG agent providing simple integration of PIV hardware (e.g. a Yubikey) with ssh, and gpg workflows such as git signing, pass encryption, or keybase chat.
piv-agent originated as a reimplementation of yubikey-agent because I needed some extra features, and also to gain a better understanding of the PIV applet on security key hardware.
piv-agent makes heavy use of the Go standard library and supplementary crypto packages, as well as piv-go and pcsclite. Thanks for the great software!

DISCLAIMER

I make no assertion about the security or otherwise of this software and I am not a cryptographer. If you are, please take a look at the code and send PRs or issues. :green_heart:

Features

implements (a subset of) both ssh-agent and gpg-agent functionality
support for multiple hardware security keys
support for multiple slots in those keys
support for multiple touch policies
all cryptographic keys are generated on the hardware security key, rather than on your laptop
- secret keys never touch your hard drive
uses systemd (Linux) or launchd (macOS) socket activation
- as a result, automatically drop the transaction on the security key and cached passphrases after some period of disuse
provides "fall-back" to traditional SSH and OpenPGP keyfiles

Design philosophy

This agent should require no interaction and in general do the right thing when security keys are plugged/unplugged, laptop is power cycled, etc.

It is highly opinionated:

Only supports 256-bit ECC keys on hardware tokens
Only supports ed25519 SSH keys on disk (~/.ssh/id_ed25519)
Requires socket activation

It makes some concession to practicality with OpenPGP:

Supports RSA signing and decryption for OpenPGP keyfiles. RSA OpenPGP keys are widespread and Debian in particular only documents RSA keys.

It tries to strike a balance between security and usability:

Takes a persistent transaction on the hardware token, effectively caching the PIN.
Caches passphrases for on-disk keys (i.e. ~/.ssh/id_ed25519) in memory, so these only need to be provided once after the agent starts.
After a period of inactivity (32 minutes by default) it exits, dropping both of these. Socket activation restarts it automatically as required.

Hardware support

Tested with:

YubiKey 5C, firmware 5.2.4

Will be tested with (once PIV support is available):

Solo V2

Any device implementing the SCard API (PC/SC), and supported by piv-go / pcsclite may work. If you have tested another device with piv-agent successfully, please send a PR adding it to this list.

Platform support

Currently tested on Linux with systemd and macOS with launchd.

Protocol / Encryption Algorithm support

Supported	Not Supported	Support Blocked (Curve25519)
✅	❌	⏳

Curve25519 algorithms are blocked on hardware support. Currently I'm only aware of Solo V2 which intends to implement this non-standard curve. Support is not yet available (see the link above).

ssh-agent

	Security Key	Keyfile
ecdsa-sha2-nistp256	✅	❌
ssh-ed25519	⏳	✅

gpg-agent

	Security Key	Keyfile
ECDSA Sign (NIST Curve P-256)	✅	✅
EDDSA Sign (Curve25519)	⏳	⏳
ECDH Decrypt	✅	✅
RSA Sign	❌	✅
RSA Decrypt	❌	✅

Install and Use

Please see the documentation.

Develop

Prerequisites

Install build dependencies:

# debian/ubuntu
sudo apt install libpcsclite-dev

Build and test

make

Build and test manually

This D-Bus variable is required for pinentry to use a graphical prompt:

go build ./cmd/piv-agent && systemd-socket-activate -l /tmp/piv-agent.sock -E DBUS_SESSION_BUS_ADDRESS ./piv-agent serve --debug

Then in another terminal:

export SSH_AUTH_SOCK=/tmp/piv-agent.sock
ssh ...

Build and test the documentation

cd docs && make serve