Add a page for step-by-step gpg/keybase

website/source/docs/concepts/pgp-gpg-keybase.html.md

@@ -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): ...
+```

website/source/docs/http/sys-init.html.md

@@ -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">pgp_keys</span>
-        <span class="param-flags">optional</spam>
+        <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>

website/source/intro/getting-started/deploy.html.md

@@ -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
 

website/source/layouts/docs.erb

@@ -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 &amp; 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>