mirror of
https://github.com/hashicorp/vault.git
synced 2025-11-28 06:01:08 +01:00
Add a page for step-by-step gpg/keybase
This commit is contained in:
Seth Vargo
parent
250aa228df
commit
a263c9e6d4
154
website/source/docs/concepts/pgp-gpg-keybase.html.md
Normal file
154
website/source/docs/concepts/pgp-gpg-keybase.html.md
Normal file
@ -0,0 +1,154 @@
|
||||
---
|
||||
layout: "docs"
|
||||
page_title: "Using PGP, GPG, and Keybase"
|
||||
sidebar_current: "docs-concepts-pgp-gpg-keybase"
|
||||
description: |-
|
||||
Vault has the ability to integrate with GPG and services like Keybase.io to
|
||||
provide an additional layer of security when performing certain operations.
|
||||
This page details the various GPG integrations, their use, and operation.
|
||||
---
|
||||
|
||||
# Using PGP, GPG, and Keybase
|
||||
|
||||
Vault has the ability to integrate with GPG and services like Keybase to
|
||||
provide an additional layer of security when performing certain operations.
|
||||
This page details the various GPG integrations, their use, and operation.
|
||||
|
||||
## Initializing with GPG
|
||||
One of the fundamental problems when bootstrapping and initializing the Vault
|
||||
is that the first user (the initializer) received a plain-text copy of all 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, the
|
||||
Vault can optionally be initialized using GPG keys. In this mode, Vault will
|
||||
generate the unseal keys and then immediately encrypt them using the given
|
||||
users' GPG public 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 GPG onto the local
|
||||
machine from which you are initializing the vault. This guide will not attempt
|
||||
to cover all aspects of GPG keys. For more information, please see the
|
||||
[GPG manual](https://gnupg.org/gph/en/manual.html).
|
||||
|
||||
To create a new GPG key, run, following the prompts:
|
||||
|
||||
```
|
||||
$ gpg --gen-key
|
||||
```
|
||||
|
||||
To import an existing key, download the public key onto disk and run:
|
||||
|
||||
```
|
||||
$ gpg --import key.asc
|
||||
```
|
||||
|
||||
Once you have imported the users' public GPG keys, you need to save their values
|
||||
to disk as either base64 or binary key files. For example:
|
||||
|
||||
```
|
||||
$ gpg --export 348FFC4C | base64 > seth.asc
|
||||
```
|
||||
|
||||
These key files must exist on disk in base64 or binary. Once saved to disk, the
|
||||
path to these files can be specified as an argument to the `-pgp-keys` flag.
|
||||
|
||||
```
|
||||
$ vault init -key-shares=3 -key-threshold=2 \
|
||||
-pgp-keys="jeff.asc,vishal.asc,seth.asc"
|
||||
```
|
||||
|
||||
The result should look something like this:
|
||||
|
||||
```
|
||||
Key 1: c1c04c03d5f43b6432ea77f3010800...
|
||||
Key 2: 612b611295f255baa2eb702a5e254f...
|
||||
Key 3: ebfd78302325e2631bcc21e11cae00...
|
||||
...
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
### Unsealing with a GPG key
|
||||
Assuming you have been given a GPG key that was encrypted using your GPG public
|
||||
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:
|
||||
|
||||
```
|
||||
$ echo "c1c0..." | xxd -r -p | gpg -d
|
||||
```
|
||||
|
||||
And replace `c1c0...` with the encrypted key.
|
||||
|
||||
If you encrypted your key with a passphrase, you may be prompted to enter it.
|
||||
After you enter your password, the output will be the plain-text key:
|
||||
|
||||
```
|
||||
6ecb46277133e04b29bd0b1b05e60722dab7cdc684a0d3ee2de50ce4c38a357101
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
$ vault unseal
|
||||
Key (will be hidden): ...
|
||||
```
|
||||
|
||||
- - -
|
||||
|
||||
## Initializing with Keybase
|
||||
[Keybase.io](https://keybase.io) is a popular online service that aims to verify
|
||||
and prove users' identies using a number of online sources. Keybase also exposes
|
||||
the ability for users to have PGP keys generated, stored, and managed securely
|
||||
on their servers.
|
||||
|
||||
To generate unseal keys for keybase users, Vault accepts the `keybase:` prefix
|
||||
to the `-pgp-keys` argument:
|
||||
|
||||
```
|
||||
$ vault init -key-shares=3 -key-threshold=2 \
|
||||
-pgp-keys="keybase:jefferai,keybase:vishalnayak,keybase:sethvargo"
|
||||
```
|
||||
|
||||
This requires far fewer steps that traditional GPG because keybase handles a
|
||||
few of the tedious steps. The output will be the similar to the following:
|
||||
|
||||
```
|
||||
Key 1: c1c04c03d5f43b6432ea77f3010800...
|
||||
Key 2: 612b611295f255baa2eb702a5e254f...
|
||||
Key 3: ebfd78302325e2631bcc21e11cae00...
|
||||
...
|
||||
```
|
||||
|
||||
### Unsealing with Keybase
|
||||
As a user, you must have the keybase CLI tool installed. You can download it
|
||||
from [keybase.io](https://keybase.io). 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:
|
||||
|
||||
```
|
||||
$ echo "c1c0..." | xxd -r -p | keybase pgp decrypt
|
||||
```
|
||||
|
||||
And replace `c1c0...` with the encrypted key.
|
||||
|
||||
You will be prompted to enter your keybase passphrase. The output will be the
|
||||
plain-text unseal key.
|
||||
|
||||
```
|
||||
6ecb46277133e04b29bd0b1b05e60722dab7cdc684a0d3ee2de50ce4c38a357101
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
$ vault unseal
|
||||
Key (will be hidden): ...
|
||||
```
|
||||
@ -61,8 +61,8 @@ description: |-
|
||||
This must be less than or equal to <code>secret_shares</code>.
|
||||
</li>
|
||||
<li>
|
||||
<spam class="param">pgp_keys</span>
|
||||
<span class="param-flags">optional</spam>
|
||||
<span class="param">pgp_keys</span>
|
||||
<span class="param-flags">optional</span>
|
||||
An array of PGP public keys used to encrypt the output unseal keys.
|
||||
Ordering is preserved. The keys must be base64-encoded from their
|
||||
original binary representation. The size of this array must be the
|
||||
@ -84,4 +84,10 @@ description: |-
|
||||
```
|
||||
|
||||
</dd>
|
||||
|
||||
<dt>See Also</dt>
|
||||
<dd>
|
||||
For more information on the GPG/keybase process please see the
|
||||
[Vault GPG and Keybase integration documentation](/docs/concepts/pgp-gpg-keybase.html).
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
@ -120,15 +120,7 @@ Key 5: b47fdeb7dda82dbe92d88d3c860f605005
|
||||
Initial Root Token: eaf5cc32-b48f-7785-5c94-90b5ce300e9b
|
||||
|
||||
Vault initialized with 5 keys and a key threshold of 3!
|
||||
|
||||
Please securely distribute the above keys. Whenever a Vault server
|
||||
is started, it must be unsealed with 3 (the threshold)
|
||||
of the keys above (any of the keys, as long as the total number equals
|
||||
the threshold).
|
||||
|
||||
Vault does not store the original master key. If you lose the keys
|
||||
above such that you no longer have the minimum number (the
|
||||
threshold), then your Vault will not be able to be unsealed.
|
||||
...
|
||||
```
|
||||
|
||||
Initialization outputs two incredibly important pieces of information:
|
||||
@ -138,7 +130,11 @@ only time that the unseal keys should ever be so close together.
|
||||
|
||||
For the purpose of this getting started guide, save all these keys
|
||||
somewhere, and continue. In a real deployment scenario, you would never
|
||||
save these keys together.
|
||||
save these keys together. Instead, you would likely use Vault's PGP and
|
||||
keybase support to encrypt each of these keys with the users' GPG keys.
|
||||
This prevents one single person from having all the unseal keys. Please
|
||||
see the documentation on [using PGP keys with Vault](/docs/concepts/pgp-gpg-keybase-integration.html)
|
||||
for more information.
|
||||
|
||||
## Seal/Unseal
|
||||
|
||||
|
||||
@ -36,7 +36,7 @@
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-install") %>>
|
||||
<a href="/docs/install/index.html">Install & Upgrade</a>
|
||||
<a href="/docs/install/index.html">Install & Upgrade</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-concepts") %>>
|
||||
@ -69,6 +69,10 @@
|
||||
<li<%= sidebar_current("docs-concepts-ha") %>>
|
||||
<a href="/docs/concepts/ha.html">High Availability</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-concepts-pgp-gpg-keybase") %>>
|
||||
<a href="/docs/concepts/pgp-gpg-keybase.html">PGP, GPG, and Keybase</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user