PIV Agent Documentation on PIV Agent

Install

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites#

Consider redundancy#

If you lose access to your hardware security device (for example if it is lost, stolen, or broken) there is no way to recover the keys stored on it. For that reason it is highly recommended that you use fallback SSH or age keyfiles and/or multiple hardware security devices.

Install pcsclite#

piv-agent has transitive dependencies through piv-go, on pcsclite.

# debian / ubuntu
sudo apt install libpcsclite1
# TODO: other platforms
...

Install piv-agent#

Download the latest release, and extract it to a temporary location. Copy the piv-agent binary into your $PATH, and the systemd unit files to the correct location:

Setup

Mon, 01 Jan 0001 00:00:00 +0000

Hardware#

Default setup#

This procedure resets the state of the PIV applet to factory defaults and wipes any existing keys from all PIV slots.

This procedure is only required once per hardware security device. Performing it a second time will reset the keys on the PIV applet of the device. It will not make any changes to applets providing other functionality the device may have, such as WebAuthn.

By default, piv-agent uses up to six slots on your hardware security device to set up three signing keys, and up to three decrypting keys. Each of the signing and decrypting keys have different touch policies: never required, cached (for 15 seconds), and always.

Use

Mon, 01 Jan 0001 00:00:00 +0000

Start `piv-agent.socket`#

Start the agent sockets, and test:

systemctl --user enable --now piv-agent.socket
ssh-add -l

This should be enough to allow you to use piv-agent.

Common operations#

List keys#

piv-agent status

If this command returns an empty list, it may be because the running agent is holding a transaction to the hardware security device. The solution is to stop the agent and run the list command again.

systemctl --user stop piv-agent
# should work now..
piv-agent status

Encrypting and Decrypting with age#

You can list your age identities and their associated recipients by using the status command:

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

How does age-plugin-piv-agent compare to age-plugin-yubikey?#

Firstly, age-plugin-yubikey is created by professional cryptographic engineers, and has a much larger user base. piv-agent has neither attribute, so you should probably just use age-plugin-yubikey.

That said, here are the technical differences I am aware of in the design of these two pieces of software.

age-plugin-yubikey:

supports multiple age key types
stores the ML-KEM seed in the metadata of the certificate stored in a slot. It is stored on the YubiKey hardware, but is publicly readable when the YubiKey is plugged in.
is multi-platform.

piv-agent:

PIV Agent Documentation on PIV Agent

Install

Prerequisites#

Consider redundancy#

Install pcsclite#

Install piv-agent#

Setup

Hardware#

Default setup#

Use

Start piv-agent.socket#

Common operations#

List keys#

Encrypting and Decrypting with age#

FAQ

How does age-plugin-piv-agent compare to age-plugin-yubikey?#

Start `piv-agent.socket`#