From e6f65cb194f229dff4e9694a8ddfb66cddd64020 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Mon, 13 Apr 2015 20:41:53 -0700 Subject: [PATCH] website: seal concept --- website/source/docs/concepts/seal.html.md | 72 +++++++++++++++++++++++ website/source/layouts/docs.erb | 6 ++ 2 files changed, 78 insertions(+) create mode 100644 website/source/docs/concepts/seal.html.md diff --git a/website/source/docs/concepts/seal.html.md b/website/source/docs/concepts/seal.html.md new file mode 100644 index 000000000..e8894ad56 --- /dev/null +++ b/website/source/docs/concepts/seal.html.md @@ -0,0 +1,72 @@ +--- +layout: "docs" +page_title: "Seal/Unseal" +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 +[Shamir's Secret Sharing](http://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) +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 + +The unseal process is done by running `vault unseal` or via the API. +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 +address this, but for now it is a design decision: you want the unsealing +shards to be in the hands of operators, and you want each unseal to be +a careful event. For HA, please use multiple Vault servers. + +## Sealing + +There is also an API to seal the Vault. This will throw away the encryption +key and require another unseal process to restore it. Sealing only requires +a single operator with root privileges. + +This way, if there is a detected intrustion, the Vault data can be locked +quickly to try to minimize damages. It can't be accessed again without +access to the master key shards. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 087cfa9c5..940c0243b 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -29,6 +29,12 @@ > "Dev" Server + + > + Seal/Unseal + + +