$ pivy-agent -g 995E171383029CDA0D9CDBDBAD580813 bash$ ssh-add -l256 SHA256:PJ6ucGKUqlQhiJdArDaF65+AVImg8SVq77vL6nVE/ME PIV_slot_9C /CN=Digital Signature (ECDSA)256 SHA256:U86TVxP/gxVk4CQibIWit3Q+/5i4aZuXa2NALIahjww PIV_slot_9E /CN=Card Authentication (ECDSA)

$ ssh user@hostsign_and_send_pubkey: signing failed: agent refused operationuser@host: Permission denied (publickey).

$ ssh-add -XEnter lock password:Agent unlocked.$ ssh user@hostLast login: Wed Mar 28 21:56:11 2018 from laptop[user@host ~]$

Connection confirm mode

You can also start thepivy-agent with mode-C, which indicates that itshould prompt for confirmation (by running the program specified in theSSH_CONFIRM environment variable).

Unlike the regularssh-agent,pivy-agent only prompts for confirmation onceper connection to the agent, and only for connections which are forwarded viaSSH agent forwarding (unless you give the option twice, as-CC, in which caseevery connection is confirmed). This makes the option more suitable for regularuse: local programs don’t necessarily need prompting, and programs which makerepeated use of your keys to perform operations will only pop up one prompt.

TheSSH_CONFIRM environment variable can be given as a path to thezenitytool if desired — pivy-agent will generate appropriate arguments itself.

If you use agent forwarding (ssh -A), use of this mode is highly recommended.

GUI prompts

pivy-agent supports the sameSSH_ASKPASS environment variable and interfacethatssh-add does for presenting a GUI prompt for the PIN if desired.

If the environment variableSSH_NOTIFY_SEND is set to a path to a commandwhich acts likenotify-send (takes two arguments, title and message), thenpivy-agent will also run that command whenever it believes a touchconfirmation may be required.

$ pivy-tool list      card: 562A20E4    device: Yubico YubiKey OTP+FIDO+CCID 00 00     chuid: ok      guid: 562A20E42ED0E5813C530ED7FE75BE92    fasc-n: 00000000000000000000000000000000000000000000000000    expiry: 2050-01-01    yubico: implements YubicoPIV extensions (v5.1.2)    serial: 9073851      auth: PIN*     slots:           ID   TYPE    BITS  CERTIFICATE           9e   ECDSA   256   /title=piv-card-auth/CN=562A20E42ED0E5813C530ED7FE75BE92           9a   ECDSA   256   /title=piv-auth/CN=562A20E42ED0E5813C530ED7FE75BE92           9c   RSA     2048  /title=piv-sign/CN=562A20E42ED0E5813C530ED7FE75BE92           9d   ECDSA   256   /title=piv-key-mgmt/CN=562A20E42ED0E5813C530ED7FE75BE92

$ pivy-toolpivy-tool: operation requiredusage: pivy-tool [options] <operation>Available operations:  list                   Lists PIV tokens present  pubkey <slot>          Outputs a public key in SSH format  cert <slot>            Outputs DER certificate from slot  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 <slot>        Generate a new private key and a                         self-signed cert  import <slot>          Accept a SSH private key on stdin                         and import it to a Yubikey (generates                         a self-signed cert to go with it)  change-pin             Changes the PIV PIN  change-puk             Changes the PIV PUK  reset-pin              Resets the PIN using the PUK  factory-reset          Factory reset the PIV applet on a                         Yubikey, once the PIN and PUK are both                         locked (max retries used)  set-admin <hex|@file>  Sets the admin 3DES key  sign <slot>            Signs data on stdin  ecdh <slot>            Do ECDH with pubkey on stdin  auth <slot>            Does a round-trip signature test to                         verify that the pubkey on stdin                         matches the one in the slot  attest <slot>          (Yubikey only) Output attestation cert                         and chain for a given slot.  box [slot]             Encrypts stdin data with an ECDH box  unbox                  Decrypts stdin data with an ECDH box                         Chooses token and slot automatically  box-info               Prints metadata about a box from stdin...

Setting up a new YubiKey and recommended usage

I recommend that new users run thepivy-tool setup command — it willinitialise the PIV applet and then generate a standard set of basic keyswhich will suit most users.

Thesetup command will prompt you to set a PIN and PUK, as well as generatingkeys. The PIV PIN and PUK are both secret strings of 6-8 ASCII characterswhich are used to protect access to your device. In the PIV spec, these stringsare required to be numeric (consisting only of digits 0 through 9), but manyPIV 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 unlockthe use of private keys. By default, 5 invalid attempts to validate the PIN areallowed before it becomes locked. The PUK is intended as a fall-back if the PINis forgotten, and can be used to reset it when locked. If you supply the PUKincorrectly 3 times (by default), then the card/device becomes locked down andwill generally destroy its private keys.

It’s fine for personal use to set the PIN and PUK to the same value. The PUKis best used in an organisational context where devices are being provisionedfor users centrally — it can be securely stored rather than given to the userand 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", whichare known by their numbered slot IDs.

The different key "slots" (9a,9c,9d and9e) have different assignedpurposes in the PIV spec, but YubiKeys and a lot of compatible devices are notvery strict in enforcing these.

If you want detailed information about how the slots are intended to be used,you should consultNIST 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 intendedto authenticate only thedevice/card, not the person who owns it. Itdefaults to not requiring any authentication to use (no PIN, no touchconfirmation on YubiKeys). Inpivy-agent, for example, this slot is usedto check that the device it’s talking to is actually the device it’s supposedto be (and not an attacker replacement with the same ID) before giving itthe user’s PIN.

• 9A: PIV Authentication Key. This is the main key used to authenticate theowner of the card/device. It’s protected by the PIN by default. You shoulduse this key as your primary option for signature authentication (e.g. thisis the key you should add to.ssh/authorized_keys or GitHub).

• 9C: Signature Key. This key is intended for use signing documents orcertificates. Since this purpose is not as common as authentication amongstusers ofpivy, it also serves duty as a backup authentication key. If youneed to SSH or auth to a system that does not support EC keys, this key isan RSA key so that you can use it as a fallback for the9A key. It requiresa PIN by default, like9A.

• 9D: Key Management Key. This key is intended for use only to derivesymmetric keys to encrypt/decrypt data. It’s a matter of some controversyin the cryptography community whether it’s entirely safe to use the same ECkey both for signing and key derivation (ECDH), so I would recommend youavoid signing arbitrary data with your9D key (don’t use it for regularauthentication). See the next section for more information about using thiskey to encrypt data at rest. Requires both PIN and touch confirmation (onYubiKeys).

As well as these 4 basic slots, there are also the "Retired Key Management"slots,82 through95. These are intended for rolling old previously-used9D keys into so that you can continue to decrypt data protected by them ona new device. However, as usual, YubiKeys do not enforce this usage, and theseslots can be used for anything you like.

If you need to import an existing key into your YubiKey, I would recommend usingone of these retired slots rather than placing it in one of the "main 4".

Note that using thepivy-agent for SSH authentication becomes more complexwhen you have more than 4 keys available — most SSH servers default toMaxAuthTries 6 in their configuration, and each key counts as a "try", soif you connect with an agent that contains 6 keys, no other auth methods can beattempted (so you will never fall back to trying password/interactive auth). Ifneeded, you can work around this with theIdentitesOnly SSH configurationoption.

Templates

Since the N/M recovery setup can involve a lot of typing (entering informationabout 5+ tokens),pivy-box lets you save just the metadata about which tokensyou want to use for your recovery setup in a "template" file. These aremanaged by thepivy-box tpl family of commands:

Thepivy-box tpl create andtpl edit commands also include an interactivemenu-driven editor so you can make changes later:

Of course, editing a template does not automatically re-encrypt any eboxes youhave already created from it. There is a re-encrypt command available underkey andstream though to help you update to a new template.

Types of eboxes

There are two different types of ebox supported:

• A "key" ebox for storing small amounts of key material or other fixed-lengthdata (e.g. disk encryption master keys); and

• A "stream" ebox which can handle large amounts of data without bufferingit all into memory, and can also be used in a seekable form.

In both types, no data is ever output by thepivy-box command from decryptionunless it has passed MAC validation (i.e. all forms available are authenticatedencryption).

ZFS encryption

An example of using a "key" ebox with ZFS encryption:

Thepivy-zfs tool wraps these steps up into single commands:

Thepivy-zfs unlock command also will prompt you to add a new primary tokenif you finish recovery successfully, which also makes it preferable to scriptingthezfs load-key command yourself.

LUKS/cryptsetup

With LUKS/cryptsetup we can store the ebox data in a LUKS2 JSON token slot. Thepivy-luks tool handles formatting and unlocking LUKS2 partitions with theraw volume key encoded directly in the ebox and no passphrase keyslot:

Othercryptsetup commands work on apivy-luks partition as normal:

Note that the resulting LUKS header has no keyslots (so there is no passphrasethat will unlock the volume key for this partition, only the ebox).

Recovery and challenge-response

Whenpivy-box key unlock orpivy-box stream decrypt run and cannot locatea "primary" token on the system that matches the box they are decrypting, theyenter an interactive recovery mode on the terminal.

First, recovery mode will prompt you to select the configuration and partsyou want to use for the 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 generatechallenges for remote recovery:

These base64-encoded challenge tokens are encrypted so that only the targetdevice can process them or retrieve any sensitive information. They do not,however, have any means to authenticate thesending machine on their own,which is the purpose of the "verification words".

As a result, you should transport the verification words separately to thechallenge itself — e.g. send the challenge over IRC or email, but send theverification words over Signal or read them over the phone.

The challenge does include additional information that can be verified totry to reduce the risk of replay as well, which will be displayed on theremote machine.

An example of responding to a challenge:

Responses to a challenge are not replayable, so they do not need separateverification words.

$ git clone https://github.com/arekinath/pivy$ cd pivy$ make

$ make setupEnter a GUID to use for pivy-agent: 995E171383029CDA0D9CDBDBAD580813install -d /home/alex/.config/pivy-agentinstall .dist/default_config /home/alex/.config/pivy-agent/defaultsystemctl --user enable pivy-agent@default.servicesystemctl --user start pivy-agent@default.serviceAdd the following lines to your .profile or .bashrc:  export PATH=/opt/pivy/bin:$PATH  if [[ ! -e "$SSH_AUTH_SOCK" || "$SSH_AUTH_SOCK" == *"/keyring/"* ]]; then    export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR/pivy-ssh-default.socket"  fi

Differences to Linux

There is one known issue on OSX currently: the PCSC framework does not workafter callingfork(), which forces thepivy-agent code to not be able to runin the background (this means usingpivy-agent bash to start a shell doesn’twork, for example). The best way to usepivy-agent on OSX is set up as alaunchd service.

Compiling on Mac OSX

Rather than depend on homebrew or MacPorts or another similar system, we buildlibressl-portable in a subdirectory and statically link the binaries againstit. 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 relatedtools or libraries on OSX — the PCSC framework built into the operating systemitself works fine forpivy-agent.

The commands you will need to run are as follows: