Master and unseal keys clarification

I’ve just started learning Vault and faced 2 pages with conflicting (in my opinion) information about unseal and encryption processes. I apologize for huge quote sections below, but this will make my question very clear.

Seal/Unseal page contains the text below, which I understand in the following way - Vault has an encryption key (for encrypting most of its data), which is encrypted by master key, which is encrypted by unseal key that is distributed in the form of shards:

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 master key .
Therefore, to decrypt the data, Vault must decrypt the encryption key which requires the master key. Unsealing is the process of getting access to this master key. The master 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 master key; and the master key is encrypted by the unseal key.
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 shards. A certain threshold of shards is required to reconstruct the unseal key, which is then used to decrypt 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 master key.

Then there is the architecture page with the text below, which I understand as this - Vault has an encryption key, which is encrypted by master key, which is itself distributed in the form of shards (just to explicitly point out - there is no unseal key).

Once started, the Vault is in a sealed state. Before any operation can be performed on the Vault it must be unsealed. This is done by providing the unseal keys. When the Vault is initialized it generates an encryption key which is used to protect all the data. That key is protected by a master key. By default, Vault uses a technique known as Shamir’s secret sharing algorithm to split the master key into 5 shares, any 3 of which are required to reconstruct the master key.

Also, if you look at pictures on these pages representing relationships between the keys, they are indeed different. One shows that unseal key is split into shards, while another shows that master key is split into shards.

Please, help me understand where I am missing something. Is this really a conflicting description?

Hi @wise-Kaas,

The architecture page is out of date, it’s describing the pre-Vault-1.3 behaviour. I’ll work on an update to it, thanks for calling it out.

2 Likes