Docs

[fmeringdal]

Describe the bug In https://github.com/hashicorp/vault/blob/main/website/content/docs/concepts/seal.mdx the docs states:

The master key is stored alongside all other Vault data

But here https://learn.hashicorp.com/tutorials/vault/rekeying-and-rotating?in=vault/operations it states:

Vault never stores the master key, therefore, the only way to retrieve the master key is to have a quorum of unseal keys re-generate it.

I believe these are contradictory statements and that the latter statement is correct, but I could be wrong. I am sorry if I have misunderstood something...

[hghaf099]

Thank you very much for your interest in the Vault project, and also thank you for filing this issue. Our goal is to improve the quality of out product and its documentation using such good feedback from the community. With regards to this issue, note that the master key is only stored in memory (Not persisted on disk) while Vault is unsealed. However, when Vault is sealed, the master key is encrypted using the unseal key and stored along side all other Vault data.

[fmeringdal]

Thanks for your quick reply.

[hghaf099]

I made a mistake in my communication, we indeed need to fix an issue with the docs. So, the master key is always stored on disk, encrypted by the unseal key. However, when Vault is unsealed, the master key will also be kept in memory. We are going to fix the issue soon. Thanks again for filing this ticket.

[fmeringdal]

I am struggling a little bit with understanding these two statements as well.

From your comment:

So, the master key is always stored on disk, encrypted by the unseal key

From the operator init docs:

During initialization, Vault generates an in-memory master key and applies Shamir's secret sharing algorithm to disassemble that master key into a configuration number of key shares such that a configurable subset of those key shares must come together to regenerate the master key. These keys are often called "unseal keys" in Vault's documentation.

So from the first comment, I understand it as there is a key called "unseal key" which encrypts the master key and then that unseal key is split into shares using SSS on init.

If it is the master key that is split into shares on init as the second comment states, which of those shares are used to encrypt the master key and why is it then necessary to store the master key on disk if it can be assembled again from these shares anyways?

[hghaf099]

@fmeringdal In the older versions of Vault (up until Vault 1.3), the master key was split into a number of pieces using the SSS algorithm. However, after that Vault version, an additional key was introduced, the "unseal key", which is used to encrypt/decrypt the master key. The unseal key is now split into a configurable number of shares. This page provides the most up to date information on that process. So, the master key is not split into shares any more. We have identified these issues with the docs, and we are working to fix those in the near future.

[heatherezell]

@taoism4504 A docs update on master keys (and also, do we want to rename "master" keys to something more inclusive?)

[aphorise]

hey @fmeringdal do you agree that the current documentation is now more accurate and if so should we close this issue?

• https://github.com/hashicorp/vault/blob/main/website/content/docs/concepts/seal.mdx#why
• https://learn.hashicorp.com/tutorials/vault/rekeying-and-rotating?in=vault/operations#rekeying-vault

[fmeringdal]

Thanks! Looks good, closing the issue