:toc: left :source-highlighter: pygments :doctype: book :idprefix: :docinfo:
Simple-to-use PIV client for Linux and OSX. Includes the tools pivy-tool,
pivy-agent, pivy-box and pivy-zfs.
This is an implementation of a simple PIV client for desktop Linux and OSX with
minimal dependencies. It contains a pivy-tool binary which can conduct basic
operations using PIV cards, and the pivy-agent, which implements the SSH agent
protocol as a drop-in replacement for the OpenSSH ssh-agent command (except
that the keys it contains are always on a PIV card).
"PIV cards" notably includes Yubico Yubikey devices such as the NEO and Yubikey4, which can store up to 24 keys by using the "retired key" slots (which this agent supports).
This project re-uses most of the agent and protocol parsing code from OpenSSH, where it's been pretty thoroughly battle-hardened.
pivy-agentUsing the PIV agent is identical to running the normal ssh-agent command,
with the exception that pivy-agent requires a -g argument specifying the
GUID of the PIV card to attach to, and you don't have to use ssh-add to load
any keys. You can also give a -K argument with the public key of the
"Card Authentication" slot (9E) for extra security.
For example, the GUID of my PIV card is 995E171383029CDA0D9CDBDBAD580813 (if
you don't know your GUID, the pivy-tool command can display it). I can use the
following command to start the pivy-agent against my card:
I can now use the 9E Card Authentication key with ssh or any other tools that
use speak the OpenSSH agent protocol (e.g. the Joyent manta and triton
tools). If I try to use the 9C Digital Signature key right now though, I will
get an error like this:
To use the 9C key I will have to give my PIV PIN to the agent so that it can
unlock the card to use the key. I can do this either by starting the agent with
an environment variable SSH_ASKPASS set (in which case I will get a graphical
prompt for the PIN), or by using the command ssh-add -X:
The PIV PIN is stored in memory only with special guard pages allocated either side of it and marked non-swappable. On Linux the memory area is also marked as non-dumpable so that it does not appear in core files.
You can make the agent forget the PIN by using the ssh-add -x command to
"lock" it. You can supply any password you like (including an empty string)
for the "lock" command. The command ssh-add -D can also be used, and will not
prompt for a password (useful from scripts).
The agent will also forget the PIN automatically if the PIV card is unavailable for more than a few minutes, or if unusual conditions occur (e.g. an attacker tries to plug in a device with the same GUID that fails the 9E signature test).
Note that it's perfectly fine to leave the pivy-agent running and remove your
PIV card: the agent will just return errors on any attempt to use it until
you insert your card again (you will need to enter your PIN again). You can
even start the agent without the PIV card present at all.
One useful way to use the pivy-agent is to set up a systemd unit file for it
to run whenever you log in, and adjust your shell profile to use it as your
normal SSH agent. Then your PIV keys are automatically ready for use in any
shell.
You can also start the pivy-agent with mode -C, which indicates that it
should prompt for confirmation (by running the program specified in the
SSH_CONFIRM environment variable).
Unlike the regular ssh-agent, pivy-agent only prompts for confirmation once
per connection to the agent, and only for connections which are forwarded via
SSH agent forwarding (unless you give the option twice, as -CC, in which case
every connection is confirmed). This makes the option more suitable for regular
use: local programs don't necessarily need prompting, and programs which make
repeated use of your keys to perform operations will only pop up one prompt.
The SSH_CONFIRM environment variable can be given as a path to the zenity
tool if desired -- pivy-agent will generate appropriate arguments itself.
If you use agent forwarding (ssh -A), use of this mode is highly recommended.
pivy-agent supports the same SSH_ASKPASS environment variable and interface
that ssh-add does for presenting a GUI prompt for the PIN if desired.
If the environment variable SSH_NOTIFY_SEND is set to a path to a command
which acts like notify-send (takes two arguments, title and message), then
pivy-agent will also run that command whenever it believes a touch
confirmation may be required.
pivy-toolThe pivy-tool program can perform a variety of operations against PIV tokens
on the system, including simply listing the available tokens and their state:
You can see a short summary of the commands available by running pivy-tool
without any arguments:
$ pivy-tool
pivy-tool: operation required
usage: pivy-tool [options]
init Writes GUID and card capabilities
(used to init a new Yubico PIV)
setup Quick setup procedure for new YubiKey
(does init + generate + change-pin +
change-puk + set-admin)
generate
sign
I recommend that new users run the pivy-tool setup command -- it will
initialise the PIV applet and then generate a standard set of basic keys
which will suit most users.
The setup command will prompt you to set a PIN and PUK, as well as generating
keys. The PIV PIN and PUK are both secret strings of 6-8 ASCII characters
which are used to protect access to your device. In the PIV spec, these strings
are required to be numeric (consisting only of digits 0 through 9), but many
PIV devices such as YubiKeys will allow a much wider variety of characters.
The PIN is what you will normally use to authenticate to your device and unlock the use of private keys. By default, 5 invalid attempts to validate the PIN are allowed before it becomes locked. The PUK is intended as a fall-back if the PIN is forgotten, and can be used to reset it when locked. If you supply the PUK incorrectly 3 times (by default), then the card/device becomes locked down and will generally destroy its private keys.
It's fine for personal use to set the PIN and PUK to the same value. The PUK is best used in an organisational context where devices are being provisioned for users centrally -- it can be securely stored rather than given to the user and used to help unlock devices when PINs have been forgotten.
In a PIV device/card, your keys are stored in a fixed set of "slots", which are known by their numbered slot IDs.
The different key "slots" (9a, 9c, 9d and 9e) have different assigned
purposes in the PIV spec, but YubiKeys and a lot of compatible devices are not
very strict in enforcing these.
If you want detailed information about how the slots are intended to be used, you should consult https://csrc.nist.gov/publications/detail/sp/800-73/4/final[NIST SP 800-73-4 (the PIV standard)], but I will attempt a short summary here:
9E: Card Authentication Key (often styled as "CAK"). This key is intended
to authenticate only the device/card, not the person who owns it. It
defaults to not requiring any authentication to use (no PIN, no touch
confirmation on YubiKeys). In pivy-agent, for example, this slot is used
to check that the device it's talking to is actually the device it's supposed
to be (and not an attacker replacement with the same ID) before giving it
the user's PIN.9A: PIV Authentication Key. This is the main key used to authenticate the
owner of the card/device. It's protected by the PIN by default. You should
use this key as your primary option for signature authentication (e.g. this
is the key you should add to .ssh/authorized_keys or GitHub).9C: Signature Key. This key is intended for use signing documents or
certificates. Since this purpose is not as common as authentication amongst
users of pivy, it also serves duty as a backup authentication key. If you
need to SSH or auth to a system that does not support EC keys, this key is
an RSA key so that you can use it as a fallback for the 9A key. It requires
a PIN by default, like 9A.9D: Key Management Key. This key is intended for use only to derive
symmetric keys to encrypt/decrypt data. It's a matter of some controversy
in the cryptography community whether it's entirely safe to use the same EC
key both for signing and key derivation (ECDH), so I would recommend you
avoid signing arbitrary data with your 9D key (don't use it for regular
authentication). See the next section for more information about using this
key to encrypt data at rest. Requires both PIN and touch confirmation (on
YubiKeys).As well as these 4 basic slots, there are also the "Retired Key Management"
slots, 82 through 95. These are intended for rolling old previously-used
9D keys into so that you can continue to decrypt data protected by them on
a new device. However, as usual, YubiKeys do not enforce this usage, and these
slots can be used for anything you like.
If you need to import an existing key into your YubiKey, I would recommend using one of these retired slots rather than placing it in one of the "main 4".
Note that using the pivy-agent for SSH authentication becomes more complex
when you have more than 4 keys available -- most SSH servers default to
MaxAuthTries 6 in their configuration, and each key counts as a "try", so
if you connect with an agent that contains 6 keys, no other auth methods can be
attempted (so you will never fall back to trying password/interactive auth). If
needed, you can work around this with the IdentitesOnly SSH configuration
option.
pivy-boxThe pivy-box command provides facilities for managing encrypted data storage
using EC keys. It's particularly notable for its approach to "recovery" to handle
the situation where your PIV token is lost or damaged.
In short, an ebox generated by pivy-box can be unlocked either by a primary
PIV token, or by a set of N/M recovery PIV tokens. For example, you can
have a primary device you use to unlock an encrypted disk, and then if that
device fails, fall back to using any 3 out of a set of 5 recovery devices
instead.
During recovery the devices being used don't have to be physically connected to the machine performing recovery, either -- a system of encrypted challenge-response messages (which you can copy-paste) can be used instead to make use of a token at a remote location.
Eboxes are designed to be small enough to fit in a LUKS token JSON slot or ZFS filesystem property so that they are colocated with the encrypted data.
The ebox primitive is based on the crypto_box in libnacl/libsodium (after
which it was named). PIV doesn't support Curve25519 today, though, so we use
EC keys on the standard NIST P curves instead. ChaCha20+Poly1305 is still the
default cipher and MAC combination used. GF^256 Shamir secret sharing is used
to achieve the N/M property during recovery.
Since the N/M recovery setup can involve a lot of typing (entering information
about 5+ tokens), pivy-box lets you save just the metadata about which tokens
you want to use for your recovery setup in a "template" file. These are
managed by the pivy-box tpl family of commands:
$ pivy-box tpl
pivy-box: operation required
pivy-box tpl
$ pivy-box tpl show -h show: invalid option -- 'h' usage: pivy-box tpl show [-r] [tpl]
Pretty-prints a template to stdout showing details of devices and configuration.
Options: -r raw input, don't base64-decode stdin
If no [tpl] or -f given, expects template input on stdin.
The pivy-box tpl create and tpl edit commands also include an interactive
menu-driven editor so you can make changes later:
$ pivy-box tpl edit -i backup -- Editing template -- Select a configuration to edit: [1] recovery: any 2 of: E6FB45BD (xk1), 051CD9B2 (xk2), D19BE1E0 (xk3)
Commands: [+] add new configuration [-] remove a configuration [w] write and exit Choice? 1 -- Editing recovery config 1 -- Select a part to edit: [1] E6FB45BD (xk1) [2] 051CD9B2 (xk2) [3] D19BE1E0 (xk3)
Commands: [n] 2 parts required to recover data (change) [+] add new part/device [-] remove a part [x] finish and return Choice? + GUID (in hex)? 562A20E42ED0E5813C530ED7FE75BE92 Key? ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoY... -- Editing part 4 -- Read-only attributes: GUID: 562A20E42ED0E5813C530ED7FE75BE92 Key: ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoY...
Select an attribute to change: [n] Name: (null) [c] Card Auth Key: (none set)
Commands: [x] finish and return Choice? n Name for part? xk4 -- Editing part 4 -- Read-only attributes: GUID: 562A20E42ED0E5813C530ED7FE75BE92 Key: ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoY...
Select an attribute to change: [n] Name: xk4 [c] Card Auth Key: (none set)
Commands: [x] finish and return Choice? x -- Editing recovery config 1 -- Select a part to edit: [1] E6FB45BD (xk1) [2] 051CD9B2 (xk2) [3] D19BE1E0 (xk3) [4] 562A20E4 (xk4)
Commands: [n] 2 parts required to recover data (change) [+] add new part/device [-] remove a part [x] finish and return Choice? x -- Editing template -- Select a configuration to edit: [1] recovery: any 2 of: E6FB45BD (xk1), 051CD9B2 (xk2), D19BE1E0 (xk3), 562A20E4 (xk4)
Of course, editing a template does not automatically re-encrypt any eboxes you
have already created from it. There is a re-encrypt command available under
key and stream though to help you update to a new template.
There are two different types of ebox supported:
In both types, no data is ever output by the pivy-box command from decryption
unless it has passed MAC validation (i.e. all forms available are authenticated
encryption).
An example of using a "key" ebox with ZFS encryption:
$ pivy-box tpl create foobar ... $ pivy-box key generate foobar -l 32 > /tmp/newkey.ebox $ pivy-box key unlock -R < /tmp/newkey.ebox | \ zfs create \ -o encryption=on -o keyformat=raw \ -o local:ebox="$(cat /tmp/newkey.ebox | tr -d '\n')" \ pool/filesystem $ rm /tmp/newkey.ebox
The pivy-zfs tool wraps these steps up into single commands:
$ pivy-box tpl create foobar ... $ pivy-zfs -t foobar zfs-create pool/filesystem
The pivy-zfs unlock command also will prompt you to add a new primary token
if you finish recovery successfully, which also makes it preferable to scripting
the zfs load-key command yourself.
With LUKS/cryptsetup we can store the ebox data in a LUKS2 JSON token slot. The
pivy-luks tool handles formatting and unlocking LUKS2 partitions with the
raw volume key encoded directly in the ebox and no passphrase keyslot:
$ pivy-box tpl create foobar ... $ pivy-luks format -t foobar /dev/sdx2
Other cryptsetup commands work on a pivy-luks partition as normal:
$ cryptsetup luksDump /dev/sdx2 LUKS header information Version: 2 Epoch: 3 Metadata area: 16384 [bytes] Keyslots area: 16744448 [bytes] UUID: c0b8d772-5418-4460-81c5-a5abe20b85fa Label: (no label) Subsystem: (no subsystem) Flags: (no flags)
Data segments: 0: crypt offset: 16777216 [bytes] length: (whole device) cipher: aes-xts-plain64 sector: 4096 [bytes]
Note that the resulting LUKS header has no keyslots (so there is no passphrase that will unlock the volume key for this partition, only the ebox).
When pivy-box key unlock or pivy-box stream decrypt run and cannot locate
a "primary" token on the system that matches the box they are decrypting, they
enter an interactive recovery mode on the terminal.
First, recovery mode will prompt you to select the configuration and parts you want to use for the recovery:
-- Recovery mode -- Select a configuration to use for recovery: [1] recovery: any 2 of: E6FB45BD (xk1), 051CD9B2 (xk2), D19BE1E0 (xk3)
Commands: Choice? 1 -- Recovery config 1 -- Select 2 parts to use for recovery [1] E6FB45BD (xk1) [2] 051CD9B2 (xk2) [3] D19BE1E0 (xk3)
Commands: Choice? 1 -- Select recovery method for part 1 -- GUID: E6FB45BDE5146C5B21FCB9409524B98C Name: xk1 Public key (9d): ecdsa-sha2-nistp256 AAAAE2VjZHNhL... [x] Do not use* [l] Use locally (directly attached to this machine) [r] Use remotely (via challenge-response)
Commands: Choice? r -- Recovery config 1 -- Select 2 parts to use for recovery [1] E6FB45BD (xk1)* [remote/challenge-response] [2] 051CD9B2 (xk2) [3] D19BE1E0 (xk3)
Commands: Choice? 2 -- Select recovery method for part 2 -- GUID: 051CD9B2177EB12374C798BB3462793E Name: xk2 Public key (9d): ecdsa-sha2-nistp256 AAAAE2VjZHN... [x] Do not use* [l] Use locally (directly attached to this machine) [r] Use remotely (via challenge-response)
Commands: Choice? r -- Recovery config 1 -- Select 2 parts to use for recovery [1] E6FB45BD (xk1) [remote/challenge-response] [2] 051CD9B2 (xk2) [remote/challenge-response] [3] D19BE1E0 (xk3) [r] begin recovery
Once sufficient parts have been selected, you can choose the "Begin recovery" option. This will first try to locate any devices you've chosen for "local" recovery, prompting for insertion as you go. Then it will proceed to generate challenges for remote recovery:
-- Begin challenge for remote device E6FB45BD (xk1) -- sMUCARDm+0W95RRsWyH8uUCVJLmMnRFjaGFjaGEyMC1wb2x5MTMwNQZzaGE1MTIQF ddAc+h16xsXZY9+WCgrBghuaXN0cDI1NiED4yZnwmPVfm0RlixV34blQg+mbRnF+G sLlhyGZojhd5YhA5Cbbob/i306qUbZpULvj9kmErWLvjVsyIiQC4ifpxM+AAAAAQB 0JgTe6DAfCdO+dfs0uJvfjStT5w2bxdVJPcP3GR+BoL4yc2ETsa15vF1ST/I0lKGV FFEy/n0MsPZb03iOxbBN40nTXVQZtaSnjpNwinegzFGf6+kq1Tj8Kvgd8N5q3YRJx J71hjgrH/lwFvSSUN3Njy8UWHDmhl9I2FHxzCUStFN/+G5Ihf5/KGyfDIzcWABcD4 wh1wBraCdIgkTftKQQDcb5dHEvtlLeronpS4YfRaqdLRgQdnznFQxV/QnACU2CTD8 olkWzgXy/kypkN97FhoJ3wltmnRSWInLTZ5WIzdTz6NkDdf61VsDcaCovcubGkVMu E090O8nuzFSdtObH -- End challenge for remote device E6FB45BD (xk1) --
VERIFICATION WORDS for E6FB45BD (xk1): apple leadership sacred breakfast
-- Begin challenge for remote device 051CD9B2 (xk2) -- sMUCARAFHNmyF36xI3THmLs0Ynk+nRFjaGFjaGEyMC1wb2x5MTMwNQZzaGE1MTIQq xtt1txRzfWNpA2VotX1jQhuaXN0cDI1NiEC+lfqlhWdzpHFqVvRrE6tYls71VNZcm ORxoIYnF9ORU4h... -- End challenge for remote device 051CD9B2 (xk2) --
VERIFICATION WORDS for 051CD9B2 (xk2): jewellery academic powder syndicate
Remaining responses required:
-- Enter response followed by newline --
These base64-encoded challenge tokens are encrypted so that only the target device can process them or retrieve any sensitive information. They do not, however, have any means to authenticate the sending machine on their own, which is the purpose of the "verification words".
As a result, you should transport the verification words separately to the challenge itself -- e.g. send the challenge over IRC or email, but send the verification words over Signal or read them over the phone.
The challenge does include additional information that can be verified to try to reduce the risk of replay as well, which will be displayed on the remote machine.
An example of responding to a challenge:
$ pivy-box challenge respond sMUCARAFHNmyF36xI3THmLs0Ynk+nRFjaGFjaGEyMC1wb2x5MTMwNQZzaGE1MTIQq xtt1txRzfWNpA2VotX1jQhuaXN0cDI1NiEC+lfqlhWdzpHFqVvRrE6tYls71VNZcm ORxoIYnF9ORU4... ^D Enter PIV PIN for token 051CD9B2: -- Challenge -- Purpose recovery of at-rest encryption keys Description Recovering pivy-box data for part 051CD9B2 (xk2) Hostname myra Generated at 2019-04-12 12:43:39 (local time)
VERIFICATION WORDS jewellery academic powder syndicate
Please check that these verification words match the original source via a separate communications channel to the one used to transport the challenge itself.
Responses to a challenge are not replayable, so they do not need separate verification words.
On Linux you will need to have a compiler and basic build tools and headers
installed, as well as the libraries pcsclite and libbsd (and their -dev
packages if your distro does those). Some musl based distros will also require
installing libedit.
If you're using ArchLinux, we have a https://aur.archlinux.org/packages/pivy[`pivy` package in the AUR] which will compile and install the binaries for you.
If you're compiling yourself, clone this repository and use make to build
the binaries:
You can then run make install (as root or with sudo) to install the agent into
/opt/pivy. The Makefile also supports prefix=/... to use a different prefix
rather than /opt/pivy, and DESTDIR= to stage the installation.
The make setup invocation can be used to set up a user systemd service to
start it automatically at login. It will also print out lines to add to your
.profile or .bashrc to make sure the agent is automatically available in
all your shells (while still preferring a forwarded SSH agent if you SSH into
your machine later).
$ make setup Enter a GUID to use for pivy-agent: 995E171383029CDA0D9CDBDBAD580813
install -d /home/alex/.config/pivy-agent install .dist/default_config /home/alex/.config/pivy-agent/default systemctl --user enable pivy-agent@default.service systemctl --user start pivy-agent@default.service
Installing on OSX is even easier, as we have pre-built binary package installers
which both install the binaries and set up a user launchd service to run the
pivy-agent for you.
You can find the latest binary installer on the https://github.com/arekinath/pivy/releases[releases page].
After installing the program itself, the installer will prompt you to insert a
YubiKey or other PIV token using a dialog box. Then it will generate a user
launchd service to run the agent for you, and add lines to /etc/profile to
default to using it in place of the Keychain agent.
The pivy- programs will also be added to your PATH, so they should be
accessible from any terminal. You'll find them in /opt/pivy if you need
them for any other reason.
There is one known issue on OSX currently: the PCSC framework does not work
after calling fork(), which forces the pivy-agent code to not be able to run
in the background (this means using pivy-agent bash to start a shell doesn't
work, for example). The best way to use pivy-agent on OSX is set up as a
launchd service.
Rather than depend on homebrew or MacPorts or another similar system, we build
libressl-portable in a subdirectory and statically link the binaries against
it. The Makefile in this repository will handle it all for you.
Note there is no need to install PCSClite or OpenSC or any of the related
tools or libraries on OSX -- the PCSC framework built into the operating system
itself works fine for pivy-agent.
The commands you will need to run are as follows:
$ git clone https://github.com/arekinath/pivy-agent $ cd pivy-agent
$ make -j4