Rename master key -> root key in docs (#14542)

This commit is contained in:
Jim Kalafut 2022-03-16 22:01:38 -07:00 committed by GitHub
parent 219df7087c
commit 9733e8b858
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
25 changed files with 81 additions and 81 deletions

View file

@ -34,7 +34,7 @@ This endpoint creates or updates a key definition.
- `url` `(string: "")` Specifies the TOTP key url string that can be used to configure a key. Only used if generate is false. - `url` `(string: "")` Specifies the TOTP key url string that can be used to configure a key. Only used if generate is false.
- `key` `(string: <required - if generate is false and url is empty>)` Specifies the master key used to generate a TOTP code. Only used if generate is false. - `key` `(string: <required - if generate is false and url is empty>)` Specifies the root key used to generate a TOTP code. Only used if generate is false.
- `issuer` `(string: "" <required - if generate is true>)`  Specifies the name of the keys issuing organization. - `issuer` `(string: "" <required - if generate is true>)`  Specifies the name of the keys issuing organization.

View file

@ -2,7 +2,7 @@
layout: api layout: api
page_title: /sys/generate-recovery-token - HTTP API page_title: /sys/generate-recovery-token - HTTP API
description: |- description: |-
The `/sys/generate-recovery-token/` endpoints are used to create a new The `/sys/generate-recovery-token/` endpoints are used to create a new
recovery token for Vault. They are only active in recovery mode. recovery token for Vault. They are only active in recovery mode.
--- ---
@ -116,8 +116,8 @@ $ curl \
## Provide Key Share to Generate Recovery Token ## Provide Key Share to Generate Recovery Token
This endpoint is used to enter a single master key share to progress the This endpoint is used to enter a single root key share to progress the
recovery token generation attempt. If the threshold number of master key shares recovery token generation attempt. If the threshold number of root key shares
is reached, Vault will complete the recovery token generation and issue the new is reached, Vault will complete the recovery token generation and issue the new
token. Otherwise, this API must be called multiple times until that threshold token. Otherwise, this API must be called multiple times until that threshold
is met. The attempt nonce must be provided with each call. is met. The attempt nonce must be provided with each call.
@ -131,7 +131,7 @@ only in memory and thus will only be valid until the next restart.
### Parameters ### Parameters
- `key` `(string: <required>)` Specifies a single master key share. - `key` `(string: <required>)` Specifies a single root key share.
- `nonce` `(string: <required>)`  Specifies the nonce of the attempt. - `nonce` `(string: <required>)`  Specifies the nonce of the attempt.

View file

@ -114,8 +114,8 @@ $ curl \
## Provide Key Share to Generate Root ## Provide Key Share to Generate Root
This endpoint is used to enter a single master key share to progress the root This endpoint is used to enter a single root key share to progress the root
generation attempt. If the threshold number of master key shares is reached, generation attempt. If the threshold number of root key shares is reached,
Vault will complete the root generation and issue the new token. Otherwise, Vault will complete the root generation and issue the new token. Otherwise,
this API must be called multiple times until that threshold is met. The attempt this API must be called multiple times until that threshold is met. The attempt
nonce must be provided with each call. nonce must be provided with each call.
@ -126,7 +126,7 @@ nonce must be provided with each call.
### Parameters ### Parameters
- `key` `(string: <required>)` Specifies a single master key share. - `key` `(string: <required>)` Specifies a single root key share.
- `nonce` `(string: <required>)`  Specifies the nonce of the attempt. - `nonce` `(string: <required>)`  Specifies the nonce of the attempt.

View file

@ -53,10 +53,10 @@ available when using Auto Unseal.
original binary representation. original binary representation.
- `secret_shares` `(int: <required>)`  Specifies the number of shares to - `secret_shares` `(int: <required>)`  Specifies the number of shares to
split the master key into. split the root key into.
- `secret_threshold` `(int: <required>)`  Specifies the number of shares - `secret_threshold` `(int: <required>)`  Specifies the number of shares
required to reconstruct the master key. This must be less than or equal required to reconstruct the root key. This must be less than or equal
`secret_shares`. If using Vault HSM with auto-unsealing, this value must be `secret_shares`. If using Vault HSM with auto-unsealing, this value must be
the same as `secret_shares`. the same as `secret_shares`.
@ -99,7 +99,7 @@ $ curl \
### Sample Response ### Sample Response
A JSON-encoded object including the (possibly encrypted, if `pgp_keys` was A JSON-encoded object including the (possibly encrypted, if `pgp_keys` was
provided) master keys, base 64 encoded master keys and initial root token: provided) root keys, base 64 encoded root keys and initial root token:
```json ```json
{ {

View file

@ -9,7 +9,7 @@ description: The `/sys/rekey` endpoints are used to rekey the unseal keys for Va
The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault. The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault.
On seals that support stored keys (e.g. HSM PKCS11), the recovery key share(s) On seals that support stored keys (e.g. HSM PKCS11), the recovery key share(s)
can be provided to rekey the master key since no unseal keys are available. The can be provided to rekey the root key since no unseal keys are available. The
secret shares, secret threshold, and stored shares parameters must be set to 1. secret shares, secret threshold, and stored shares parameters must be set to 1.
Upon successful rekey, no split unseal key shares are returned. Upon successful rekey, no split unseal key shares are returned.
@ -67,10 +67,10 @@ and starting a new rekey, which will also provide a new nonce.
### Parameters ### Parameters
- `secret_shares` `(int: <required>)`  Specifies the number of shares to split - `secret_shares` `(int: <required>)`  Specifies the number of shares to split
the master key into. the root key into.
- `secret_threshold` `(int: <required>)`  Specifies the number of shares - `secret_threshold` `(int: <required>)`  Specifies the number of shares
required to reconstruct the master key. This must be less than or equal to required to reconstruct the root key. This must be less than or equal to
`secret_shares`. `secret_shares`.
- `pgp_keys` `(array<string>: nil)`  Specifies an array of PGP public keys used - `pgp_keys` `(array<string>: nil)`  Specifies an array of PGP public keys used
@ -87,7 +87,7 @@ and starting a new rekey, which will also provide a new nonce.
functionality. When verification is turned on, after successful authorization functionality. When verification is turned on, after successful authorization
with the current unseal keys, the new unseal keys are returned but the master with the current unseal keys, the new unseal keys are returned but the master
key is not actually rotated. The new keys must be provided to authorize the key is not actually rotated. The new keys must be provided to authorize the
actual rotation of the master key. This ensures that the new keys have been actual rotation of the root key. This ensures that the new keys have been
successfully saved and protects against a risk of the keys being lost after successfully saved and protects against a risk of the keys being lost after
rotation but before they can be persisted. This can be used with or without rotation but before they can be persisted. This can be used with or without
`pgp_keys`, and when used with it, it allows ensuring that the returned keys `pgp_keys`, and when used with it, it allows ensuring that the returned keys
@ -181,8 +181,8 @@ $ curl \
## Submit Key ## Submit Key
This endpoint is used to enter a single master key share to progress the rekey This endpoint is used to enter a single root key share to progress the rekey
of the Vault. If the threshold number of master key shares is reached, Vault of the Vault. If the threshold number of root key shares is reached, Vault
will complete the rekey. Otherwise, this API must be called multiple times until will complete the rekey. Otherwise, this API must be called multiple times until
that threshold is met. The rekey nonce operation must be provided with each that threshold is met. The rekey nonce operation must be provided with each
call. call.

View file

@ -580,8 +580,8 @@ $ curl \
## Provide Key Share to Generate Token ## Provide Key Share to Generate Token
This endpoint is used to enter a single master key share to progress the This endpoint is used to enter a single root key share to progress the
generation attempt. If the threshold number of master key shares is reached, generation attempt. If the threshold number of root key shares is reached,
Vault will complete the generation and issue the new token. Otherwise, Vault will complete the generation and issue the new token. Otherwise,
this API must be called multiple times until that threshold is met. The attempt this API must be called multiple times until that threshold is met. The attempt
nonce must be provided with each call. nonce must be provided with each call.
@ -592,7 +592,7 @@ nonce must be provided with each call.
### Parameters ### Parameters
- `key` `(string: <required>)` Specifies a single master key share. - `key` `(string: <required>)` Specifies a single root key share.
- `nonce` `(string: <required>)`  Specifies the nonce of the attempt. - `nonce` `(string: <required>)`  Specifies the nonce of the attempt.

View file

@ -10,8 +10,8 @@ The `/sys/unseal` endpoint is used to unseal the Vault.
## Submit Unseal Key ## Submit Unseal Key
This endpoint is used to enter a single master key share to progress the This endpoint is used to enter a single root key share to progress the
unsealing of the Vault. If the threshold number of master key shares is reached, unsealing of the Vault. If the threshold number of root key shares is reached,
Vault will attempt to unseal the Vault. Otherwise, this API must be called Vault will attempt to unseal the Vault. Otherwise, this API must be called
multiple times until that threshold is met. multiple times until that threshold is met.
@ -24,7 +24,7 @@ Either the `key` or `reset` parameter must be provided; if both are provided,
### Parameters ### Parameters
- `key` `(string: "")` Specifies a single master key share. This is required - `key` `(string: "")` Specifies a single root key share. This is required
unless `reset` is true. unless `reset` is true.
- `reset` `(bool: false)`  Specifies if previously-provided unseal keys are - `reset` `(bool: false)`  Specifies if previously-provided unseal keys are

View file

@ -15,10 +15,10 @@ process by which Vault's storage backend is prepared to receive data. Since
Vault servers share the same storage backend in HA mode, you only need to Vault servers share the same storage backend in HA mode, you only need to
initialize one Vault to initialize the storage backend. initialize one Vault to initialize the storage backend.
During initialization, Vault generates an in-memory master key and applies During initialization, Vault generates an in-memory root key and applies
Shamir's secret sharing algorithm to disassemble that master key into a Shamir's secret sharing algorithm to disassemble that root key into a
configuration number of key shares such that a configurable subset of those key 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 shares must come together to regenerate the root key. These keys are often
called "unseal keys" in Vault's documentation. called "unseal keys" in Vault's documentation.
This command cannot be run against already-initialized Vault cluster. This command cannot be run against already-initialized Vault cluster.
@ -75,7 +75,7 @@ flags](/docs/commands) included on all commands.
`-n`. `-n`.
- `-key-threshold` `(int: 3)` - Number of key shares required to reconstruct the - `-key-threshold` `(int: 3)` - Number of key shares required to reconstruct the
master key. This must be less than or equal to -key-shares. This is aliased as root key. This must be less than or equal to -key-shares. This is aliased as
`-t`. `-t`.
- `-pgp-keys` `(string: "...")` - Comma-separated list of paths to files on disk - `-pgp-keys` `(string: "...")` - Comma-separated list of paths to files on disk

View file

@ -4,7 +4,7 @@ page_title: operator rekey - Command
description: |- description: |-
The "operator rekey" command generates a new set of unseal keys. This can The "operator rekey" command generates a new set of unseal keys. This can
optionally change the total number of key shares or the required threshold of optionally change the total number of key shares or the required threshold of
those key shares to reconstruct the master key. This operation is zero those key shares to reconstruct the root key. This operation is zero
downtime, but it requires the Vault is unsealed and a quorum of existing downtime, but it requires the Vault is unsealed and a quorum of existing
unseal keys are provided. unseal keys are provided.
--- ---
@ -13,7 +13,7 @@ description: |-
The `operator rekey` command generates a new set of unseal keys. This can The `operator rekey` command generates a new set of unseal keys. This can
optionally change the total number of key shares or the required threshold of optionally change the total number of key shares or the required threshold of
those key shares to reconstruct the master key. This operation is zero downtime, those key shares to reconstruct the root key. This operation is zero downtime,
but it requires the Vault is unsealed and a quorum of existing unseal keys are but it requires the Vault is unsealed and a quorum of existing unseal keys are
provided. provided.
@ -128,7 +128,7 @@ flags](/docs/commands) included on all commands.
`-n` `-n`
- `-key-threshold` `(int: 3)` - Number of key shares required to reconstruct the - `-key-threshold` `(int: 3)` - Number of key shares required to reconstruct the
master key. This must be less than or equal to -key-shares. This is aliased as root key. This must be less than or equal to -key-shares. This is aliased as
`-t`. `-t`.
- `-nonce` `(string: "")` - Nonce value provided at initialization. The same - `-nonce` `(string: "")` - Nonce value provided at initialization. The same

View file

@ -7,7 +7,7 @@ description: >-
stop responding to any operations until it is unsealed. When sealed, the Vault stop responding to any operations until it is unsealed. When sealed, the Vault
server discards its in-memory master key to unlock the data, so it is server discards its in-memory root key to unlock the data, so it is
physically blocked from responding to operations unsealed. physically blocked from responding to operations unsealed.
--- ---
@ -16,11 +16,11 @@ description: >-
The `operator seal` seals the Vault server. Sealing tells the Vault server to The `operator seal` seals the Vault server. Sealing tells the Vault server to
stop responding to any operations until it is unsealed. When sealed, the Vault stop responding to any operations until it is unsealed. When sealed, the Vault
server discards its in-memory master key to unlock the data, so it is physically server discards its in-memory root key to unlock the data, so it is physically
blocked from responding to operations unsealed. blocked from responding to operations unsealed.
If an unseal is in progress, sealing the Vault will reset the unsealing process. If an unseal is in progress, sealing the Vault will reset the unsealing process.
Users will have to re-enter their portions of the master key again. Users will have to re-enter their portions of the root key again.
This command does nothing if the Vault server is already sealed. This command does nothing if the Vault server is already sealed.

View file

@ -2,13 +2,13 @@
layout: docs layout: docs
page_title: operator unseal - Command page_title: operator unseal - Command
description: |- description: |-
The "operator unseal" allows the user to provide a portion of the master key The "operator unseal" allows the user to provide a portion of the root key
to unseal a Vault server. to unseal a Vault server.
--- ---
# operator unseal # operator unseal
The `operator unseal` allows the user to provide a portion of the master key to The `operator unseal` allows the user to provide a portion of the root key to
unseal a Vault server. Vault starts in a sealed state. It cannot perform unseal a Vault server. Vault starts in a sealed state. It cannot perform
operations until it is unsealed. This command accepts a portion of the master operations until it is unsealed. This command accepts a portion of the master
key (an "unseal key"). key (an "unseal key").

View file

@ -12,7 +12,7 @@ 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 state, Vault is configured to know where and how to access the physical
storage, but doesn't know how to decrypt any of it. storage, but doesn't know how to decrypt any of it.
_Unsealing_ is the process of obtaining the plaintext master key necessary to _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. read the decryption key to decrypt the data, allowing access to the Vault.
Prior to unsealing, almost no operations are possible with Vault. For Prior to unsealing, almost no operations are possible with Vault. For
@ -24,15 +24,15 @@ of the seal.
The data stored by Vault is encrypted. Vault needs the _encryption key_ in order 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 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_. (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 Therefore, to decrypt the data, Vault must decrypt the encryption key
which requires the master key. Unsealing is the process of getting access to which requires the root key. Unsealing is the process of getting access to
this master key. The master key is stored alongside all other Vault data, this root key. The root key is stored alongside all other Vault data,
but is encrypted by yet another mechanism: the unseal key. but is encrypted by yet another mechanism: the unseal key.
To recap: most Vault data is encrypted using the encryption key in the keyring; 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 keyring is encrypted by the root key; and the root key is encrypted by
the unseal key. the unseal key.
## Shamir seals ## Shamir seals
@ -43,11 +43,11 @@ 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 key as a single key to an operator, Vault uses an algorithm known as
[Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) [Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing)
to split the key into shards. A certain threshold of shards is required to 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. reconstruct the unseal key, which is then used to decrypt the root key.
This is the _unseal_ process: the shards are added one at a time (in any 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 order) until enough shards are present to reconstruct the key and
decrypt the master key. decrypt the root key.
## Unsealing ## Unsealing
@ -77,7 +77,7 @@ only requires a single operator with root privileges.
This way, if there is a detected intrusion, the Vault data can be locked 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 quickly to try to minimize damages. It can't be accessed again without
access to the master key shards. access to the root key shards.
## Auto Unseal ## Auto Unseal
@ -85,7 +85,7 @@ Auto Unseal was developed to aid in reducing the operational complexity of
keeping the unseal key secure. This feature delegates the responsibility 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 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 Vault will connect to the device or service implementing the seal and ask it
to decrypt the master key Vault read from storage. to decrypt the root key Vault read from storage.
![AutoUnseal](/img/vault-autounseal-storage.png) ![AutoUnseal](/img/vault-autounseal-storage.png)
@ -98,7 +98,7 @@ keys_ instead.
Just as the initialization process with a Shamir seal yields unseal keys, Just as the initialization process with a Shamir seal yields unseal keys,
initializing with an Auto Unseal yields recovery keys. initializing with an Auto Unseal yields recovery keys.
-> **Note:** Recovery keys cannot decrypt the master key, and thus are not -> **Note:** Recovery keys cannot decrypt the root key, and thus are not
sufficient to unseal Vault if the AutoUnseal mechanism isn't working. They sufficient to unseal Vault if the AutoUnseal mechanism isn't working. They
are purely an authorization mechanism. are purely an authorization mechanism.

View file

@ -205,7 +205,7 @@ The following parameters are used on backends that support [high availability][h
The following parameters are only used with Vault Enterprise The following parameters are only used with Vault Enterprise
- `disable_sealwrap` `(bool: false)`  Disables using [seal wrapping][sealwrap] - `disable_sealwrap` `(bool: false)`  Disables using [seal wrapping][sealwrap]
for any value except the master key. If this value is toggled, the new for any value except the root key. If this value is toggled, the new
behavior will happen lazily (as values are read or written). behavior will happen lazily (as values are read or written).
- `disable_performance_standby` `(bool: false)` Specifies whether performance - `disable_performance_standby` `(bool: false)` Specifies whether performance

View file

@ -104,7 +104,7 @@ Vault Seal specific values:
## Key Rotation ## Key Rotation
This seal supports rotating the master keys defined in AWS KMS This seal supports rotating the root keys defined in AWS KMS
[doc](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html). Both automatic [doc](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html). Both automatic
rotation and manual rotation is supported for KMS since the key information is stored with the rotation and manual rotation is supported for KMS since the key information is stored with the
encrypted data. Old keys must not be disabled or deleted and are used to decrypt older data. encrypted data. Old keys must not be disabled or deleted and are used to decrypt older data.

View file

@ -10,8 +10,8 @@ description: >-
The `seal` stanza configures the seal type to use for additional data The `seal` stanza configures the seal type to use for additional data
protection, such as using HSM or Cloud KMS solutions to encrypt and decrypt the protection, such as using HSM or Cloud KMS solutions to encrypt and decrypt the
master key. This stanza is optional, and in the case of the master key, Vault root key. This stanza is optional, and in the case of the root key, Vault
will use the Shamir algorithm to cryptographically split the master key if this will use the Shamir algorithm to cryptographically split the root key if this
is not configured. is not configured.
As of Vault 0.9.0, the seal can also be used for [seal wrapping][sealwrap] to As of Vault 0.9.0, the seal can also be used for [seal wrapping][sealwrap] to

View file

@ -33,7 +33,7 @@ These CSPs have been selected from our previous work in [evaluating Vault for co
FIPS 140-2 guidelines for key storage and key transport](https://www.datocms-assets.com/2885/1510600487-vault_compliance_letter_fips_140-2.pdf) FIPS 140-2 guidelines for key storage and key transport](https://www.datocms-assets.com/2885/1510600487-vault_compliance_letter_fips_140-2.pdf)
and include the following: and include the following:
- Vaults master key - Vaults root key
- Keyring encryption keys - Keyring encryption keys
- Auto Unseal recovery keys - Auto Unseal recovery keys
- TLS private keys for inter-node and inter cluster communication (HA leader, raft, and replication) - TLS private keys for inter-node and inter cluster communication (HA leader, raft, and replication)

View file

@ -24,20 +24,20 @@ sets of keys: unseal keys and recovery keys.
## Unseal (Master) Key ## Unseal (Master) Key
Vault usually generates a master key and splits it using [Shamir's Secret Vault usually generates a root key and splits it using [Shamir's Secret
Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) to prevent a Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) to prevent a
single operator from being able to modify and unseal Vault (see more single operator from being able to modify and unseal Vault (see more
information about Vault's security model information about Vault's security model
[here](/docs/internals/security)). [here](/docs/internals/security)).
When using an HSM, Vault instead stores the master key, encrypted by the HSM, When using an HSM, Vault instead stores the root key, encrypted by the HSM,
into its internal storage. As a result, during an `init` command, the number of into its internal storage. As a result, during an `init` command, the number of
key shares, threshold, and stored shares are required to be set to `1`, meaning key shares, threshold, and stored shares are required to be set to `1`, meaning
to not split the master key, so that the single key share is itself the master to not split the root key, so that the single key share is itself the master
key. (Vault does not do this automatically as it generally prefers to error key. (Vault does not do this automatically as it generally prefers to error
rather than change parameters set by an operator.) rather than change parameters set by an operator.)
Both rekeying the master key and rotation of the underlying data Both rekeying the root key and rotation of the underlying data
encryption key are supported when using an HSM. encryption key are supported when using an HSM.
## Recovery Key ## Recovery Key

View file

@ -2,7 +2,7 @@
layout: docs layout: docs
page_title: HSM Integration - Vault Enterprise page_title: HSM Integration - Vault Enterprise
description: >- description: >-
Vault Enterprise has HSM support, allowing for external master key storage and Vault Enterprise has HSM support, allowing for external root key storage and
automatic unsealing. automatic unsealing.
--- ---
@ -10,9 +10,9 @@ description: >-
-> **Note**: This feature requires [Vault Enterprise Plus](https://www.hashicorp.com/products/vault/). -> **Note**: This feature requires [Vault Enterprise Plus](https://www.hashicorp.com/products/vault/).
- Master Key Wrapping: Vault protects its master key by transiting it through - Root key Wrapping: Vault protects its root key by transiting it through
the HSM for encryption rather than splitting into key shares the HSM for encryption rather than splitting into key shares
- Automatic Unsealing: Vault stores its HSM-wrapped master key in storage, - Automatic Unsealing: Vault stores its HSM-wrapped root key in storage,
allowing for automatic unsealing allowing for automatic unsealing
- [Seal Wrapping](/docs/enterprise/sealwrap) to provide FIPS - [Seal Wrapping](/docs/enterprise/sealwrap) to provide FIPS
KeyStorage-conforming functionality for Critical Security Parameters KeyStorage-conforming functionality for Critical Security Parameters

View file

@ -26,7 +26,7 @@ The attack surface of stolen PKCS#11 credentials depends highly on the
individual HSM, but generally speaking, it should be assumed that if an individual HSM, but generally speaking, it should be assumed that if an
attacker can see these credentials and has access to a machine on which Vault attacker can see these credentials and has access to a machine on which Vault
is running, the attacker will be able to access the HSM key protecting Vault's is running, the attacker will be able to access the HSM key protecting Vault's
master key. Therefore, it is extremely important that access to the machine on root key. Therefore, it is extremely important that access to the machine on
which Vault is running is also tightly controlled. which Vault is running is also tightly controlled.
## Recovery Key Shares Protection ## Recovery Key Shares Protection

View file

@ -29,7 +29,7 @@ functionality.
To disable seal wrapping, set `disable_sealwrap = true` in Vault's To disable seal wrapping, set `disable_sealwrap = true` in Vault's
[configuration file][configuration]. This will not affect auto-unsealing functionality; Vault's [configuration file][configuration]. This will not affect auto-unsealing functionality; Vault's
master key will still be protected by the seal wrapping mechanism. It will root key will still be protected by the seal wrapping mechanism. It will
simply prevent other storage entries within Vault from being seal wrapped. simply prevent other storage entries within Vault from being seal wrapped.
_N.B._: This is a lazy downgrade; as keys are accessed or written their seal _N.B._: This is a lazy downgrade; as keys are accessed or written their seal
@ -63,7 +63,7 @@ evaluated by the auditors.
## Activating Seal Wrapping ## Activating Seal Wrapping
For some values, seal wrapping is always enabled with a supporting seal. This For some values, seal wrapping is always enabled with a supporting seal. This
includes the recovery key, any stored key shares, the master key, the keyring, includes the recovery key, any stored key shares, the root key, the keyring,
and more; essentially, any Critical Security Parameter (CSP) within Vault's and more; essentially, any Critical Security Parameter (CSP) within Vault's
core. If upgrading from a version of Vault that did not support seal wrapping, core. If upgrading from a version of Vault that did not support seal wrapping,
the next time these values are read they will be seal-wrapped and stored. the next time these values are read they will be seal-wrapped and stored.

View file

@ -39,7 +39,7 @@ allows users to authenticate via GitHub.
### Barrier ### Barrier
Almost everything Vault writes to storage is encrypted using the keyring, which is protected by the seal. We refer to this practice as "the barrier". There are a few exceptions to the rule, for example, the seal configuration is stored in an unencrypted file since it's needed to unseal the barrier, and the keyring is encrypted using the master key, while the master key is encrypted using the seal. Almost everything Vault writes to storage is encrypted using the keyring, which is protected by the seal. We refer to this practice as "the barrier". There are a few exceptions to the rule, for example, the seal configuration is stored in an unencrypted file since it's needed to unseal the barrier, and the keyring is encrypted using the root key, while the root key is encrypted using the seal.
### Client Token ### Client Token

View file

@ -36,16 +36,16 @@ by the Vault server on start so that clients can interact with it.
Once started, the Vault is in a _sealed_ state. Before any operation can be 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 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 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, to protect all the data. That key is protected by a root key. By default,
Vault uses a technique known as [Shamir's secret sharing Vault uses a technique known as [Shamir's secret sharing
algorithm](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing) to split the algorithm](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing) to split the
master key into 5 shares, any 3 of which are required to reconstruct the master root key into 5 shares, any 3 of which are required to reconstruct the master
key. key.
[![Vault Shamir Secret Sharing Algorithm](/img/vault-shamir-secret-sharing.svg)](/img/vault-shamir-secret-sharing.svg) [![Vault Shamir Secret Sharing Algorithm](/img/vault-shamir-secret-sharing.svg)](/img/vault-shamir-secret-sharing.svg)
The number of shares and the minimum threshold required can both be specified. The number of shares and the minimum threshold required can both be specified.
Shamir's technique can be disabled, and the master key can be used directly for Shamir's technique can be disabled, and the root key can be used directly for
unsealing. Once Vault retrieves the encryption key, it is able to decrypt the unsealing. Once Vault retrieves the encryption key, it is able to decrypt the
data in the storage backend, and enters the _unsealed_ state. Once unsealed, data in the storage backend, and enters the _unsealed_ state. Once unsealed,
Vault loads all of the configured audit devices, auth methods, and secrets Vault loads all of the configured audit devices, auth methods, and secrets

View file

@ -13,25 +13,25 @@ compromise. It is useful to first understand the
As a review, Vault starts in a _sealed_ state. Vault is unsealed by providing the unseal keys. As a review, Vault starts in a _sealed_ state. Vault is unsealed by providing the unseal keys.
By default, Vault uses a technique known as [Shamir's secret sharing algorithm](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing) By default, Vault uses a technique known as [Shamir's secret sharing algorithm](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing)
to split the master key into 5 shares, any 3 of which are required to reconstruct the master to split the root key into 5 shares, any 3 of which are required to reconstruct the master
key. The master key is used to protect the encryption key, which is ultimately used to protect key. The root key is used to protect the encryption key, which is ultimately used to protect
data written to the storage backend. data written to the storage backend.
[![Vault Shamir Secret Sharing Algorithm](/img/vault-shamir-secret-sharing.svg)](/img/vault-shamir-secret-sharing.svg) [![Vault Shamir Secret Sharing Algorithm](/img/vault-shamir-secret-sharing.svg)](/img/vault-shamir-secret-sharing.svg)
To support key rotation, we need to support changing the unseal keys, master key, and the To support key rotation, we need to support changing the unseal keys, root key, and the
backend encryption key. We split this into two separate operations, `rekey` and `rotate`. backend encryption key. We split this into two separate operations, `rekey` and `rotate`.
The `rekey` operation is used to generate a new master key. When this is being done, The `rekey` operation is used to generate a new root key. When this is being done,
it is possible to change the parameters of the key splitting, so that the number of shares it is possible to change the parameters of the key splitting, so that the number of shares
and the threshold required to unseal can be changed. To perform a rekey a threshold of the and the threshold required to unseal can be changed. To perform a rekey a threshold of the
current unseal keys must be provided. This is to prevent a single malicious operator from current unseal keys must be provided. This is to prevent a single malicious operator from
performing a rekey and invalidating the existing master key. performing a rekey and invalidating the existing root key.
Performing a rekey is fairly straightforward. The rekey operation must be initialized with Performing a rekey is fairly straightforward. The rekey operation must be initialized with
the new parameters for the split and threshold. Once initialized, the current unseal keys the new parameters for the split and threshold. Once initialized, the current unseal keys
must be provided until the threshold is met. Once met, Vault will generate the new master must be provided until the threshold is met. Once met, Vault will generate the new master
key, perform the splitting, and re-encrypt the encryption key with the new master key. key, perform the splitting, and re-encrypt the encryption key with the new root key.
The new unseal keys are then provided to the operator, and the old unseal keys are no The new unseal keys are then provided to the operator, and the old unseal keys are no
longer usable. longer usable.
@ -72,4 +72,4 @@ Operators can estimate the number of encryptions by summing the following:
- The `vault.barrier.put` telemetry metric. - The `vault.barrier.put` telemetry metric.
- The `vault.token.creation` metric where the `token_type` label is `batch`. - The `vault.token.creation` metric where the `token_type` label is `batch`.
- The `merkle.flushDirty.num_pages` metric. - The `merkle.flushDirty.num_pages` metric.
- The WAL index. - The WAL index.

View file

@ -156,17 +156,17 @@ Secret Sharing
technique](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing). When Vault technique](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing). When Vault
is started, it starts in a _sealed_ state. This means that the encryption key is started, it starts in a _sealed_ state. This means that the encryption key
needed to read and write from the storage backend is not yet known. The process needed to read and write from the storage backend is not yet known. The process
of unsealing requires providing the master key so that the encryption key can of unsealing requires providing the root key so that the encryption key can
be retrieved. The risk of distributing the master key is that a single be retrieved. The risk of distributing the root key is that a single
malicious actor with access to it can decrypt the entire Vault. Instead, malicious actor with access to it can decrypt the entire Vault. Instead,
Shamir's technique allows us to split the master key into multiple shares or Shamir's technique allows us to split the root key into multiple shares or
parts. The number of shares and the threshold needed is configurable, but by parts. The number of shares and the threshold needed is configurable, but by
default Vault generates 5 shares, any 3 of which must be provided to default Vault generates 5 shares, any 3 of which must be provided to
reconstruct the master key. reconstruct the root key.
By using a secret sharing technique, we avoid the need to place absolute trust By using a secret sharing technique, we avoid the need to place absolute trust
in the holder of the master key, and avoid storing the master key at all. The in the holder of the root key, and avoid storing the root key at all. The
master key is only retrievable by reconstructing the shares. The shares are not root key is only retrievable by reconstructing the shares. The shares are not
useful for making any requests to Vault, and can only be used for unsealing. useful for making any requests to Vault, and can only be used for unsealing.
Once unsealed the standard ACL mechanisms are used for all requests. Once unsealed the standard ACL mechanisms are used for all requests.
@ -178,6 +178,6 @@ steel and concrete protecting the data. While you could tunnel through the
concrete or brute force the encryption keys, it would be prohibitively time concrete or brute force the encryption keys, it would be prohibitively time
consuming. Opening the bank vault requires two-factors: the key and the consuming. Opening the bank vault requires two-factors: the key and the
combination. Similarly, Vault requires multiple shares be provided to combination. Similarly, Vault requires multiple shares be provided to
reconstruct the master key. Once unsealed, each security deposit boxes still reconstruct the root key. Once unsealed, each security deposit boxes still
requires the owner provide a key, and similarly the Vault ACL system protects requires the owner provide a key, and similarly the Vault ACL system protects
all the secrets stored. all the secrets stored.

View file

@ -128,8 +128,8 @@ distribute the key shares printed above. When the Vault is re-sealed,
restarted, or stopped, you must supply at least 3 of these keys to unseal it restarted, or stopped, you must supply at least 3 of these keys to unseal it
before it can start servicing requests. before it can start servicing requests.
Vault does not store the generated master key. Without at least 3 keys to Vault does not store the generated root key. Without at least 3 keys to
reconstruct the master key, Vault will remain permanently sealed! reconstruct the root key, Vault will remain permanently sealed!
It is possible to generate new unseal keys, provided you have a quorum of It is possible to generate new unseal keys, provided you have a quorum of
existing unseal keys shares. See "vault operator rekey" for more information. existing unseal keys shares. See "vault operator rekey" for more information.
@ -165,7 +165,7 @@ the Vault, you need 3 of the 5 keys that were generated.
-> **Note:** Vault does not store any of the unseal key shards. Vault -> **Note:** Vault does not store any of the unseal key shards. Vault
uses an algorithm known as uses an algorithm known as
[Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) [Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing)
to split the master key into shards. Only with the threshold number of keys to split the root key into shards. Only with the threshold number of keys
can it be reconstructed and your data finally accessed. can it be reconstructed and your data finally accessed.
Begin unsealing the Vault: Begin unsealing the Vault: