2015-04-14 03:41:53 +00:00
|
|
|
---
|
|
|
|
layout: "docs"
|
|
|
|
page_title: "Seal/Unseal"
|
New Docs Website (#5535)
* conversion stage 1
* correct image paths
* add sidebar title to frontmatter
* docs/concepts and docs/internals
* configuration docs and multi-level nav corrections
* commands docs, index file corrections, small item nav correction
* secrets converted
* auth
* add enterprise and agent docs
* add extra dividers
* secret section, wip
* correct sidebar nav title in front matter for apu section, start working on api items
* auth and backend, a couple directory structure fixes
* remove old docs
* intro side nav converted
* reset sidebar styles, add hashi-global-styles
* basic styling for nav sidebar
* folder collapse functionality
* patch up border length on last list item
* wip restructure for content component
* taking middleman hacking to the extreme, but its working
* small css fix
* add new mega nav
* fix a small mistake from the rebase
* fix a content resolution issue with middleman
* title a couple missing docs pages
* update deps, remove temporary markup
* community page
* footer to layout, community page css adjustments
* wip downloads page
* deps updated, downloads page ready
* fix community page
* homepage progress
* add components, adjust spacing
* docs and api landing pages
* a bunch of fixes, add docs and api landing pages
* update deps, add deploy scripts
* add readme note
* update deploy command
* overview page, index title
* Update doc fields
Note this still requires the link fields to be populated -- this is solely related to copy on the description fields
* Update api_basic_categories.yml
Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages.
* Add bottom hero, adjust CSS, responsive friendly
* Add mega nav title
* homepage adjustments, asset boosts
* small fixes
* docs page styling fixes
* meganav title
* some category link corrections
* Update API categories page
updated to reflect the second level headings for api categories
* Update docs_detailed_categories.yml
Updated to represent the existing docs structure
* Update docs_detailed_categories.yml
* docs page data fix, extra operator page remove
* api data fix
* fix makefile
* update deps, add product subnav to docs and api landing pages
* Rearrange non-hands-on guides to _docs_
Since there is no place for these on learn.hashicorp, we'll put them
under _docs_.
* WIP Redirects for guides to docs
* content and component updates
* font weight hotfix, redirects
* fix guides and intro sidenavs
* fix some redirects
* small style tweaks
* Redirects to learn and internally to docs
* Remove redirect to `/vault`
* Remove `.html` from destination on redirects
* fix incorrect index redirect
* final touchups
* address feedback from michell for makefile and product downloads
2018-10-19 15:40:11 +00:00
|
|
|
sidebar_title: "Seal/Unseal"
|
2015-04-14 03:41:53 +00:00
|
|
|
sidebar_current: "docs-concepts-seal"
|
|
|
|
description: |-
|
|
|
|
A Vault must be unsealed before it can access its data. Likewise, it can be sealed to lock it down.
|
|
|
|
---
|
|
|
|
|
|
|
|
# Seal/Unseal
|
|
|
|
|
|
|
|
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 constructing the master 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 unseal.
|
|
|
|
|
|
|
|
## Why?
|
|
|
|
|
|
|
|
The data stored by Vault is stored encrypted. Vault needs the
|
|
|
|
_encryption key_ in order to decrypt the data. The encryption key is
|
|
|
|
also stored with the data, but encrypted with another encryption key
|
|
|
|
known as the _master key_. The master key isn't stored anywhere.
|
|
|
|
|
|
|
|
Therefore, to decrypt the data, Vault must decrypt the encryption key
|
|
|
|
which requires the master key. Unsealing is the process of reconstructing
|
|
|
|
this master key.
|
|
|
|
|
|
|
|
Instead of distributing this master key as a single key to an operator,
|
|
|
|
Vault uses an algorithm known as
|
2016-01-14 18:42:47 +00:00
|
|
|
[Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing)
|
2015-04-14 03:41:53 +00:00
|
|
|
to split the key into shards. A certain threshold of shards is required to
|
|
|
|
reconstruct the master key.
|
|
|
|
|
|
|
|
This is the _unseal_ process: the shards are added one at a time (in any
|
|
|
|
order) until enough shards are present to reconstruct the key and
|
|
|
|
decrypt the data.
|
|
|
|
|
|
|
|
## Unsealing
|
|
|
|
|
2018-06-07 04:11:21 +00:00
|
|
|
The unseal process is done by running `vault operator unseal` or via the API.
|
2015-04-14 03:41:53 +00:00
|
|
|
This process is stateful: each key can be entered via multiple mechanisms
|
|
|
|
on multiple computers and it will work. This allows each shard of the master
|
|
|
|
key to be on a distinct machine for better security.
|
|
|
|
|
|
|
|
Once a Vault is unsealed, it remains unsealed until one of two things happens:
|
|
|
|
|
|
|
|
1. It is resealed via the API (see below).
|
|
|
|
|
|
|
|
2. The server is restarted.
|
|
|
|
|
|
|
|
-> **Note:** Unsealing makes the process of automating a Vault install
|
|
|
|
difficult. Automated tools can easily install, configure, and start Vault,
|
|
|
|
but unsealing it is a very manual process. We have plans in the future to
|
2015-04-17 19:01:20 +00:00
|
|
|
make it easier. For the time being, the best method is to manually unseal
|
|
|
|
multiple Vault servers in [HA mode](/docs/concepts/ha.html). Use a tool such
|
|
|
|
as Consul to make sure you only query Vault servers that are unsealed.
|
2015-04-14 03:41:53 +00:00
|
|
|
|
|
|
|
## Sealing
|
|
|
|
|
2016-01-19 15:42:50 +00:00
|
|
|
There is also an API to seal the Vault. This will throw away the master
|
2015-04-14 03:41:53 +00:00
|
|
|
key and require another unseal process to restore it. Sealing only requires
|
|
|
|
a single operator with root privileges.
|
|
|
|
|
2015-04-28 18:32:04 +00:00
|
|
|
This way, if there is a detected intrusion, the Vault data can be locked
|
2015-04-14 03:41:53 +00:00
|
|
|
quickly to try to minimize damages. It can't be accessed again without
|
|
|
|
access to the master key shards.
|
2018-10-25 23:44:53 +00:00
|
|
|
|
|
|
|
## Auto Unseal
|
|
|
|
|
2019-10-16 15:25:41 +00:00
|
|
|
Auto Unseal was developed to aid in reducing the operational complexity of
|
|
|
|
keeping the master key secure. This feature delegates the responsibility of
|
|
|
|
securing the master key from users to a trusted device or service. Instead of
|
|
|
|
only constructing the key in memory, the master key is encrypted with one of
|
|
|
|
these services or devices and then stored in the storage backend allowing Vault
|
|
|
|
to decrypt the master key at startup and unseal automatically.
|
2018-10-25 23:44:53 +00:00
|
|
|
|
2019-04-01 12:23:46 +00:00
|
|
|
When using Auto Unseal there are certain operations in Vault that still
|
2019-10-16 15:25:41 +00:00
|
|
|
require a quorum of users to perform an operation such as generating a root token.
|
|
|
|
During the initialization process, a set of Shamir keys are generated that are called
|
2018-10-25 23:44:53 +00:00
|
|
|
Recovery Keys and are used for these operations.
|
|
|
|
|
|
|
|
For a list of examples and supported providers, please see the
|
|
|
|
[seal documentation](/docs/configuration/seal/index.html).
|
|
|
|
|
|
|
|
## Seal Migration
|
|
|
|
|
2019-02-28 02:27:36 +00:00
|
|
|
The seal can be migrated from Shamir keys to Auto Unseal and vice versa.
|
2018-10-25 23:44:53 +00:00
|
|
|
|
2019-10-16 15:25:41 +00:00
|
|
|
~> **NOTE**: This is not currently supported when using Vault Enterprise Replication.
|
|
|
|
While the primary can be migrated without issue, the secondaries, depending on
|
2018-11-12 14:41:05 +00:00
|
|
|
which type of seal is being migrated from/to, may not work correctly. We plan
|
2019-03-25 16:44:22 +00:00
|
|
|
to support this officially in a future release.
|
2018-11-12 14:41:05 +00:00
|
|
|
|
2018-10-25 23:44:53 +00:00
|
|
|
To migrate from Shamir keys to Auto Unseal, take your server cluster offline and update
|
|
|
|
the [seal configuration](/docs/configuration/seal/index.html) with the appropriate seal
|
2019-10-16 15:25:41 +00:00
|
|
|
configuration. Bring your server back up and leave the rest of the nodes offline if
|
|
|
|
using multi-server mode, then run the unseal process with the `-migrate` flag and bring
|
|
|
|
the rest of the cluster online.
|
|
|
|
|
|
|
|
All unseal commands must specify the `-migrate` flag. Once the required threshold of
|
|
|
|
unseal keys are entered, unseal keys will be migrated to recovery keys.
|
2018-10-25 23:44:53 +00:00
|
|
|
|
|
|
|
```
|
2018-10-26 17:04:51 +00:00
|
|
|
$ vault operator unseal -migrate
|
2018-10-25 23:44:53 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
To migrate from Auto Unseal to Shamir keys, take your server cluster offline and update
|
|
|
|
the [seal configuration](/docs/configuration/seal/index.html) and add `disabled = "true"`
|
|
|
|
to the seal block. This allows the migration to use this information to decrypt the key
|
2019-10-16 15:25:41 +00:00
|
|
|
but will not unseal Vault. When you bring your server back up, run the unseal process
|
|
|
|
with the `-migrate` flag and use the Recovery Keys to perform the migration. All unseal
|
2019-04-01 12:23:46 +00:00
|
|
|
commands must specify the `-migrate` flag. Once the required threshold of recovery keys
|
2018-10-25 23:44:53 +00:00
|
|
|
are entered, the recovery keys will be migrated to be used as unseal keys.
|
2019-10-16 15:25:41 +00:00
|
|
|
|
|
|
|
## Recovery Key Rekeying
|
|
|
|
|
|
|
|
During Auto Seal initialization process, a set of Shamir keys called Recovery Keys are
|
|
|
|
generated which are used for operations that still require a quorum of users.
|
|
|
|
|
|
|
|
Recovery Keys can be rekeyed to change the number of shares or thresholds. When using the
|
|
|
|
Vault CLI, this is performed by using the `-target=recovery` flag to `vault operator rekey`.
|