vervet 🐒

A simple CLI tool for securely performing common Vault unseal key operations. Unseal keys are secured by private keys that are stored in hardware via the YubiKey OpenPGP application. Vervet streamlines Vault unseal key decryption and common unseal key workflows into single commands for ease of use. Yubico YubiKeys ensure that private keys used to decrypt Vault unseal keys are stored in hardware and non-exportable. Vervet is designed for Vault key officers responsible for managing unseal and recovery keys.

YubiKeys 5 series and above implement the OpenPGP application by emulating an ISO-compliant smart card. This allows vervet to use standard APDU commands to interact with the OpenPGP application. Vervet currently only supports Yubico YubiKeys and will ignore other smart card manufacturers. At this time, OpenPGP management operations such as key generation, key export, and PIN/PUK changes must take via other utility. GNU Privacy Guard offers full support for the OpenPGP application on ISO smart cards.

Please reference Dr. Duh's YubiKey Guide for additional information on securely generating, handling, and storing PGP keys.

Features

• Written in uncomplicated Go (Golang)
• Simplifies common Vault unseal key workflows
• Provides a central location for securely storing Vault unseal keys
• Enables non-exportable hardware storage for PGP keys that encrypt unseal keys
• Easy to use
• Works on Mac, Linux and (maybe) Windows

Installation

$ git clone git@github.com:onryo/vervet.git
$ cd vervet
$ make install

Usage

Commands:

generate-root     Generate Vault root token
help              Help about any command
list              List connected YubiKeys and configured Vault clusters
rekey             Rekey Vault
show              Show details of YubiKeys and Vault clusters
unseal            Unseal Vault by server or cluster

Configuration

The default vervet configuration file location is ~/.vervet/vervet.hcl. The configuration file can be overridden at runtime with the --config flag. Keys can be specified directly in the configuration file using the keys attribute. Alternatively, keys can be placed in a separate file and linked via the key_file attribute. Vervet will open key files relative to the ~/.vervet directory. Keys located in a seprate key file should be base64 encoded and new line delimited. Any duplicate unseal keys will be automatically deduplicated.

cluster "us-west" {
    servers = [
        "https://prod-vault-01.example.local:8200",
        "https://prod-vault-02.example.local:8200",
        "https://prod-vault-03.example.local:8200"
    ]
    keys = [
        "base64-encoded Vault unseal key"
    ]
    key_file = "us-west.pgp"
}

cluster "us-east" {
    [...]
}

List clusters and YubiKeys

$ vervet list clusters    # list Vault clusters defined in vervet configuration

$ vervet list yubikeys    # list connected YubiKeys that support OpenPGP

Unseal

$ vervet unseal cluster us-west    # decrypts unseal key(s) and unseals us-west Vault servers

To unseal an individual server:

$ vervet unseal server prod-vault-01.example.local key_file.pgp    # decrypt unseal key in key_file.pgp and unseal prod-vault-01

Rekey

The rekey command submits your YubiKey-decrypted unseal key share toward an in-progress rekey operation. The rekey process must be initiated separately (e.g. via vault operator rekey -init) before running vervet.

Rekey a cluster (uses the first server in the cluster config):

$ vervet rekey cluster us-west

Rekey an individual server:

$ vervet rekey server prod-vault-01.example.local key_file.pgp

The --nonce / -n flag is required when submitting to an already-started rekey:

$ vervet rekey cluster us-west --nonce b2467027-2c91-f39f-7163-68bf4c2610df

Once all required key shares have been submitted, vervet prints the new PGP-encrypted key shares alongside their PGP fingerprints.

Retrieving backup keys

If the rekey was initiated with -backup=true (the default for vervet-managed clusters), Vault stores a backup of the encrypted new key shares. Retrieve them at any time:

vault operator rekey -backup-retrieve -format=json \
  | jq -r '.data.keys["<PGP_FINGERPRINT_UPPERCASE">][]'

Delete the backup once it has been safely stored:

vault operator rekey -backup-delete

Generate root token

$ vervet generate-root cluster us-west    # generate token for us-west Vault cluster

To target an individual server for root token generation:

$ vervet generate-root server prod-vault-01.example.local key_file.pgp    # decrypt unseal key in key_file.pgp and generate root token

Contributing

Bug Reports & Feature Requests

Please use the issue tracker to report any bugs or file feature requests.

Developing

PRs are welcome. To begin developing, do this:

$ git clone git@github.com:onryo/vervet.git
$ cd vervet
$ make
$ ./bin/vervet

Acknowledgements

Vervet would not be possible without the following projects and resources.

• HashiCorp Vault
• ebfe/scard - Go bindings to the PC/SC API
• Go Cryptography
• Go Ethereum
• Cobra
• Viper
• Functional Specification of the OpenPGP application on ISO Smart Card Operating Systems
• RFC 4880 - OpenPGP Message Format
• joe - README file inspiration
• Dr. Duh's YubiKey Guide