Rename master key -> root key in docs (#14542)
This commit is contained in:
parent
219df7087c
commit
9733e8b858
|
@ -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 key’s issuing organization.
|
- `issuer` `(string: "" <required - if generate is true>)` – Specifies the name of the key’s issuing organization.
|
||||||
|
|
||||||
|
|
|
@ -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.
|
||||||
|
|
||||||
|
|
|
@ -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.
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
{
|
{
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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.
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
||||||
|
|
|
@ -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").
|
||||||
|
|
|
@ -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.
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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:
|
||||||
|
|
||||||
- Vault’s master key
|
- Vault’s 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)
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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:
|
||||||
|
|
Loading…
Reference in a new issue