Unseal/Seal

When a Vault server is started, it starts in a sealed state. In this state, Vault is configured to know where and how to access the physical storage, but doesn't know how to decrypt any of it.

Unsealing is the process of obtaining the plaintext root key necessary to read the decryption key to decrypt the data, allowing access to the Vault.

Prior to unsealing, almost no operations are possible with Vault. For example authentication, managing the mount tables, etc. are all not possible. The only possible operations are to unseal the Vault and check the status of the seal.

Why?

The data stored by Vault is encrypted. Vault needs the encryption key in order to decrypt the data. The encryption key is also stored with the data (in the keyring), but encrypted with another encryption key known as the root key.

Therefore, to decrypt the data, Vault must decrypt the encryption key which requires the root key. Unsealing is the process of getting access to this root key. The root key is stored alongside all other Vault data, but is encrypted by yet another mechanism: the unseal key.

To recap: most Vault data is encrypted using the encryption key in the keyring; the keyring is encrypted by the root key; and the root key is encrypted by the unseal key.

Shamir seals

The default Vault config uses a Shamir seal. Instead of distributing the unseal key as a single key to an operator, Vault uses an algorithm known as Shamir's Secret Sharing to split the key into shares. A certain threshold of shares is required to reconstruct the unseal key, which is then used to decrypt the root key.

This is the unseal process: the shares are added one at a time (in any order) until enough shares are present to reconstruct the key and decrypt the root key.

Unsealing

The unseal process is done by running vault operator unseal or via the API. This process is stateful: each key can be entered via multiple mechanisms from multiple client machines and it will work. This allows each shares of the root key to be on a distinct client machine for better security.

Note that when using the Shamir seal with multiple nodes, each node must be unsealed with the required threshold of shares. Partial unsealing of each node is not distributed across the cluster.

Once a Vault node is unsealed, it remains unsealed until one of these things happens:

1. It is resealed via the API (see below).

2. The server is restarted.

3. Vault's storage layer encounters an unrecoverable error.

-> Note: Unsealing makes the process of automating a Vault install difficult. Automated tools can easily install, configure, and start Vault, but unsealing it using Shamir is a very manual process. For most users Auto Unseal will provide a better experience.

Sealing

There is also an API to seal the Vault. This will throw away the root key in memory and require another unseal process to restore it. Sealing only requires a single operator with root privileges.

This way, if there is a detected intrusion, the Vault data can be locked quickly to try to minimize damages. It can't be accessed again without access to the root key shares.

Auto unseal

Auto Unseal was developed to aid in reducing the operational complexity of keeping the unseal key secure. This feature delegates the responsibility of securing the unseal key from users to a trusted device or service. At startup Vault will connect to the device or service implementing the seal and ask it to decrypt the root key Vault read from storage.

There are certain operations in Vault besides unsealing that require a quorum of users to perform, e.g. generating a root token. When using a Shamir seal the unseal keys must be provided to authorize these operations. When using Auto Unseal these operations require recovery keys instead.

Just as the initialization process with a Shamir seal yields unseal keys, initializing with an Auto Unseal yields recovery keys.

It is still possible to seal a Vault node using the API. In this case Vault will remain sealed until restarted, or the unseal API is used, which with Auto Unseal requires the recovery key fragments instead of the unseal key fragments that would be provided with Shamir. The process remains the same.

For a list of examples and supported providers, please see the seal documentation.

-> Warning: Recovery keys cannot decrypt the root key, and thus are not sufficient to unseal Vault if the Auto Unseal mechanism isn't working. They are purely an authorization mechanism. Using Auto Unseal creates a strict Vault lifecycle dependency on the underlying seal mechanism. This means that if the seal mechanism (such as the Cloud KMS key) becomes unavailable, or deleted before the seal is migrated, then there is no ability to recover access to the Vault cluster until the mechanism is available again. If the seal mechanism or its keys are permanently deleted, then the Vault cluster cannot be recovered, even from backups. To mitigate this risk, we recommend careful controls around management of the seal mechanism, for example using AWS Service Control Policies or similar.

Recovery key

When Vault is initialized while using an HSM or KMS, rather than unseal keys being returned to the operator, recovery keys are returned. These are generated from an internal recovery key that is split via Shamir's Secret Sharing, similar to Vault's treatment of unseal keys when running without an HSM or KMS.

Details about initialization and rekeying follow. When performing an operation that uses recovery keys, such as generate-root, selection of the recovery keys for this purpose, rather than the barrier unseal keys, is automatic.

Initialization

When initializing, the split is performed according to the following CLI flags and their API equivalents in the /sys/init endpoint:

• recovery-shares: The number of shares into which to split the recovery key. This value is equivalent to the recovery_shares value in the API endpoint.

• recovery-threshold: The threshold of shares required to reconstruct the recovery key. This value is equivalent to the recovery_threshold value in the API endpoint.

• recovery-pgp-keys: The PGP keys to use to encrypt the returned recovery key shares. This value is equivalent to the recovery_pgp_keys value in the API endpoint, although as with pgp_keys the object in the API endpoint is an array, not a string.

Additionally, Vault will refuse to initialize if the option has not been set to generate a key, and no key is found. See Configuration for more details.

Rekeying

Unseal key

Vault's unseal key can be rekeyed using a normal vault operator rekey operation from the CLI or the matching API calls. The rekey operation is authorized by meeting the threshold of recovery keys. After rekeying, the new barrier key is wrapped by the HSM or KMS and stored like the previous key; it is not returned to the users that submitted their recovery keys.

Recovery key

The recovery key can be rekeyed to change the number of shares/threshold or to target different key holders via different PGP keys. When using the Vault CLI, this is performed by using the -target=recovery flag to vault operator rekey.

Via the API, the rekey operation is performed with the same parameters as the normal /sys/rekey endpoint; however, the API prefix for this operation is at /sys/rekey-recovery-key rather than /sys/rekey.