1--- 2layout: "docs" 3page_title: "Using PGP, GPG, and Keybase" 4sidebar_title: "PGP, GPG, and Keybase" 5sidebar_current: "docs-concepts-pgp-gpg-keybase" 6description: |- 7 Vault has the ability to integrate with OpenPGP-compatible programs like GPG 8 and services like Keybase.io to provide an additional layer of security when 9 performing certain operations. This page details the various GPG 10 integrations, their use, and operation. 11--- 12 13# Using PGP, GPG, and Keybase 14 15Vault has the ability to integrate with OpenPGP-compatible programs like GPG 16and services like Keybase.io to provide an additional layer of security when 17performing certain operations. This page details the various PGP integrations, 18their use, and operation. 19 20Keybase.io support is available only in the command-line tool and not via the 21Vault HTTP API, tools that help with initialization should use the Keybase.io 22API in order to obtain the GPG keys needed for a secure initialization if you 23want them to use Keybase for keys. 24 25Once the Vault has been initialized, it is possible to use Keybase to decrypt 26the shards and unseal normally. 27 28## Initializing with PGP 29One of the early fundamental problems when bootstrapping and initializing Vault 30was that the first user (the initializer) received a plain-text copy of all of 31the unseal keys. This defeats the promises of Vault's security model, and it 32also makes the distribution of those keys more difficult. Since Vault 0.3, 33Vault can optionally be initialized using PGP keys. In this mode, Vault will 34generate the unseal keys and then immediately encrypt them using the given 35users' public PGP keys. Only the owner of the corresponding private key is then 36able to decrypt the value, revealing the plain-text unseal key. 37 38First, you must create, acquire, or import the appropriate key(s) onto the 39local machine from which you are initializing Vault. This guide will not 40attempt to cover all aspects of PGP keys but give examples using two popular 41programs: Keybase and GPG. 42 43For beginners, we suggest using [Keybase.io](https://keybase.io/) ("Keybase") 44as it can be both simpler and has a number of useful behaviors and properties 45around key management, such as verification of users' identities using a number 46of public online sources. It also exposes the ability for users to have PGP 47keys generated, stored, and managed securely on their servers. Using Vault with 48Keybase will be discussed first as it is simpler. 49 50## Initializing with Keybase 51To generate unseal keys for Keybase users, Vault accepts the `keybase:` prefix 52to the `-pgp-keys` argument: 53 54``` 55$ vault operator init -key-shares=3 -key-threshold=2 \ 56 -pgp-keys="keybase:jefferai,keybase:vishalnayak,keybase:sethvargo" 57``` 58 59This requires far fewer steps than traditional PGP (e.g. with `gpg`) because 60Keybase handles a few of the tedious steps. The output will be the similar to 61the following: 62 63``` 64Key 1: wcBMA37rwGt6FS1VAQgAk1q8XQh6yc... 65Key 2: wcBMA0wwnMXgRzYYAQgAavqbTCxZGD... 66Key 3: wcFMA2DjqDb4YhTAARAAeTFyYxPmUd... 67... 68``` 69 70The output should be rather long in comparison to a regular unseal key. These 71keys are encrypted, and only the user holding the corresponding private key can 72decrypt the value. The keys are encrypted in the order in which specified in 73the `-pgp-keys` attribute. As such, the keys belong to respective Keybase 74accounts of `jefferai`, `vishalnayak`, and `sethvargo`. These keys can be 75distributed over almost any medium, although common sense and judgement are 76best advised. The encrypted keys are base64 encoded before returning. 77 78 79### Unsealing with Keybase 80As a user, the easiest way to decrypt your unseal key is with the Keybase CLI 81tool. You can download it from [Keybase.io download 82page](https://keybase.io/download). After you have downloaded and configured 83the Keybase CLI, you are now tasked with entering your unseal key. To get the 84plain-text unseal key, you must decrypt the value given to you by the 85initializer. To get the plain-text value, run the following command: 86 87``` 88$ echo "wcBMA37..." | base64 --decode | keybase pgp decrypt 89``` 90 91And replace `wcBMA37...` with the encrypted key. 92 93You will be prompted to enter your Keybase passphrase. The output will be the 94plain-text unseal key. 95 96``` 976ecb46277133e04b29bd0b1b05e60722dab7cdc684a0d3ee2de50ce4c38a357101 98``` 99 100This is your unseal key in plain-text and should be guarded the same way you 101guard a password. Now you can enter your key to the `unseal` command: 102 103``` 104$ vault operator unseal 105Key (will be hidden): ... 106``` 107 108- - - 109 110## Initializing with GPG 111GPG is an open-source implementation of the OpenPGP standard and is available 112on nearly every platform. For more information, please see the [GPG 113manual](https://gnupg.org/gph/en/manual.html). 114 115To create a new PGP key, run, following the prompts: 116 117``` 118$ gpg --gen-key 119``` 120 121To import an existing key, download the public key onto disk and run: 122 123``` 124$ gpg --import key.asc 125``` 126 127Once you have imported the users' public keys, you need to save their values 128to disk as either base64 or binary key files. For example: 129 130``` 131$ gpg --export 348FFC4C | base64 > seth.asc 132``` 133 134These key files must exist on disk in base64 (the "standard" base64 character set, 135without ASCII armoring) or binary. Once saved to disk, the path to these files 136can be specified as an argument to the `-pgp-keys` flag. 137 138``` 139$ vault operator init -key-shares=3 -key-threshold=2 \ 140 -pgp-keys="jeff.asc,vishal.asc,seth.asc" 141``` 142 143The result should look something like this: 144 145``` 146Key 1: wcBMA37rwGt6FS1VAQgAk1q8XQh6yc... 147Key 2: wcBMA0wwnMXgRzYYAQgAavqbTCxZGD... 148Key 3: wcFMA2DjqDb4YhTAARAAeTFyYxPmUd... 149... 150``` 151 152The output should be rather long in comparison to a regular unseal key. These 153keys are encrypted, and only the user holding the corresponding private key 154can decrypt the value. The keys are encrypted in the order in which specified 155in the `-pgp-keys` attribute. As such, the first key belongs to Jeff, the second 156to Vishal, and the third to Seth. These keys can be distributed over almost any 157medium, although common sense and judgement are best advised. The encrypted 158keys are base64 encoded before returning. 159 160### Unsealing with a GPG 161Assuming you have been given an unseal key that was encrypted using your public 162PGP key, you are now tasked with entering your unseal key. To get the 163plain-text unseal key, you must decrypt the value given to you by the 164initializer. To get the plain-text value, run the following command: 165 166``` 167$ echo "wcBMA37..." | base64 --decode | gpg -dq 168``` 169 170And replace `wcBMA37...` with the encrypted key. 171 172If you encrypted your private PGP key with a passphrase, you may be prompted to 173enter it. After you enter your password, the output will be the plain-text 174key: 175 176``` 1776ecb46277133e04b29bd0b1b05e60722dab7cdc684a0d3ee2de50ce4c38a357101 178``` 179 180This is your unseal key in plain-text and should be guarded the same way you 181guard a password. Now you can enter your key to the `unseal` command: 182 183``` 184$ vault operator unseal 185Key (will be hidden): ... 186``` 187