Using PGP, GnuPG, and keybase
Vault has the ability to integrate with OpenPGP-compatible programs like GnuPG and services like Keybase.io to provide an additional layer of security when performing certain operations. This page details the various PGP integrations, their use, and operation.
Keybase.io support is available only in the command-line tool and not via the Vault HTTP API, tools that help with initialization should use the Keybase.io API in order to obtain the PGP keys needed for a secure initialization if you want them to use Keybase for keys.
Once the Vault has been initialized, it is possible to use Keybase to decrypt the shards and unseal normally.
Initializing with PGP
One of the early fundamental problems when bootstrapping and initializing Vault was that the first user (the initializer) received a plain-text copy of all of the unseal keys. This defeats the promises of Vault's security model, and it also makes the distribution of those keys more difficult. Since Vault 0.3, Vault can optionally be initialized using PGP keys. In this mode, Vault will generate the unseal keys and then immediately encrypt them using the given users' public PGP keys. Only the owner of the corresponding private key is then able to decrypt the value, revealing the plain-text unseal key.
First, you must create, acquire, or import the appropriate key(s) onto the local machine from which you are initializing Vault. This guide will not attempt to cover all aspects of PGP keys but give examples using two popular programs: Keybase and GnuPG.
For beginners, we suggest using Keybase.io ("Keybase") as it can be both simpler and has a number of useful behaviors and properties around key management, such as verification of users' identities using a number of public online sources. It also exposes the ability for users to have PGP keys generated, stored, and managed securely on their servers. Using Vault with Keybase will be discussed first as it is simpler.
Initializing with keybase
To generate unseal keys for Keybase users, Vault accepts the keybase: prefix
to the -pgp-keys argument:
This requires far fewer steps than traditional PGP (e.g. with gpg) because
Keybase handles a few of the tedious steps. The output will be the similar to
the following:
The output should be rather long in comparison to a regular unseal key. These
keys are encrypted, and only the user holding the corresponding private key can
decrypt the value. The keys are encrypted in the order in which specified in
the -pgp-keys attribute. As such, the keys belong to respective Keybase
accounts of jefferai, vishalnayak, and sethvargo. These keys can be
distributed over almost any medium, although common sense and judgement are
best advised. The encrypted keys are base64 encoded before returning.
Unsealing with keybase
As a user, the easiest way to decrypt your unseal key is with the Keybase CLI tool. You can download it from Keybase.io download page. After you have downloaded and configured the Keybase CLI, you are now tasked with entering your unseal key. To get the plain-text unseal key, you must decrypt the value given to you by the initializer. To get the plain-text value, run the following command:
And replace wcBMA37... with the encrypted key.
You will be prompted to enter your Keybase passphrase. The output will be the plain-text unseal key.
This is your unseal key in plain-text and should be guarded the same way you
guard a password. Now you can enter your key to the unseal command:
Initializing with GnuPG
GnuPG is an open-source implementation of the OpenPGP standard and is available on nearly every platform. For more information, please see the GnuPG manual.
To create a new PGP key, run, following the prompts:
To import an existing key, download the public key onto disk and run:
Once you have imported the users' public keys, you need to save their values to disk as either base64 or binary key files. For example:
These key files must exist on disk in base64 (the "standard" base64 character set,
without ASCII armoring) or binary. Once saved to disk, the path to these files
can be specified as an argument to the -pgp-keys flag.
The result should look something like this:
The output should be rather long in comparison to a regular unseal key. These
keys are encrypted, and only the user holding the corresponding private key
can decrypt the value. The keys are encrypted in the order in which specified
in the -pgp-keys attribute. As such, the first key belongs to Jeff, the second
to Vishal, and the third to Seth. These keys can be distributed over almost any
medium, although common sense and judgement are best advised. The encrypted
keys are base64 encoded before returning.
Unsealing with GnuPG
Assuming you have been given an unseal key that was encrypted using your public PGP key, you are now tasked with entering your unseal key. To get the plain-text unseal key, you must decrypt the value given to you by the initializer. To get the plain-text value, run the following command:
And replace wcBMA37... with the encrypted key.
If you encrypted your private PGP key with a passphrase, you may be prompted to enter it. After you enter your password, the output will be the plain-text key:
This is your unseal key in plain-text and should be guarded the same way you
guard a password. Now you can enter your key to the unseal command: