mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-22 15:11:07 +02:00
0660ea6fac
* Update README Let contributors know that docs will now be located in UDR * Add comments to each mdx doc Comment has been added to all mdx docs that are not partials * chore: added changelog changelog check failure * wip: removed changelog * Fix content errors * Doc spacing * Update website/content/docs/deploy/kubernetes/vso/helm.mdx Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> --------- Co-authored-by: jonathanfrappier <92055993+jonathanfrappier@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
104 lines
4.3 KiB
Plaintext
104 lines
4.3 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Key Rotation
|
|
description: Learn about the details of key rotation within Vault.
|
|
---
|
|
|
|
> [!IMPORTANT]
|
|
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.
|
|
|
|
# Key rotation
|
|
|
|
Vault stores different encryption keys for different purposes. Vault uses key
|
|
rotation to periodically change the keys according to a configured limit or in
|
|
response to a potential leak or compromised service.
|
|
|
|
## Relevant key definitions
|
|
|
|
There are four keys involved in key rotation:
|
|
|
|
- **internal encryption key** - Encrypts and protects data written to the
|
|
storage backend.
|
|
- **root key** - "Master" key that seals Vault and protects the internal
|
|
encryption key.
|
|
- **unseal key** - A portion (share) of the root key used to reconstruct the
|
|
root key. By default, Vault uses the
|
|
[Shamir's secret sharing algorithm](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing)
|
|
to split the root key into 5 shares.
|
|
- **upgrade key** - A short-lived copy of the internal encryption key created
|
|
during key rotation in high-availability deployments. Vault encrypts upgrade
|
|
keys using the previous internal encryption key.
|
|
|
|
## How key rotation works
|
|
|
|
Vault supports online **rekey** and **rotate** operations to update the root
|
|
key, unseal keys, and backend encryption key even for high-availability
|
|
deployments. In replicated deployments, the active node performs the operations
|
|
and standby nodes use an upgrade key to update their keys without requiring a
|
|
manual unseal operation.
|
|
|
|
1. Rekeying begins with a configured split and threshold for unseal keys:
|
|
1. Vault receives the configured threshold of unseal keys.
|
|
1. Vault generates and splits the new root key.
|
|
1. Vault re-encrypts the internal encryption key with the new root key.
|
|
1. Vault returns the new unseal keys.
|
|
1. Rotation begins:
|
|
1. Vault generates a new internal encryption key.
|
|
1. Vault adds the new encryption key to an internal keyring.
|
|
1. Vault creates a temporary **upgrade key** (if needed).
|
|
|
|
|
|
|
|
Once the rotation completes, Vault can encrypt new writes to the storage backend
|
|
using the new key, but still decrypt entries written under the previous key.
|
|
|
|
<Tip title="Related API endpoints">
|
|
|
|
ConfigureKeyRotation - [`POST:/sys/rotate/config`](/vault/api-docs/system/rotate-config)
|
|
|
|
</Tip>
|
|
|
|
|
|
## NIST rotation guidance
|
|
|
|
The National Institute of Standards and Technology (NIST) recommends
|
|
periodically rotating encryption keys, even without a leak or compromise event.
|
|
|
|
Due to the nature of AES-256-GCM encryption,
|
|
[NIST publication 800-38D](https://csrc.nist.gov/pubs/sp/800/38/d/final)
|
|
recommends rotating keys **before** performing ~2<sup>32</sup> encryptions. By
|
|
default, Vault monitors the `vault.barrier.estimated_encryptions` metric and
|
|
automatically rotates the backend encryption key before reaching 2<sup>32</sup>
|
|
encryption operations.
|
|
|
|
You can approximate the `vault.barrier.estimated_encryptions` metric with the
|
|
following sum:
|
|
|
|
<CodeBlockConfig hideClipboard>
|
|
|
|
```text
|
|
ESTIMATED_OPS = PUT_EVENTS + CREATE_EVENTS + MERKLE_FLUSH_EVENTS + WAL_INDEX
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
where:
|
|
|
|
- **`PUT_EVENTS`** is the `vault.barrier.put` telemetry metric.
|
|
- **`CREATION_EVENTS`** is the `vault.token.creation` metric where `token_type`
|
|
is `batch`.
|
|
- **`MERKLE_FLUSH_EVENTS`** is the `merkle.flushDirty.num_pages` telemetry metric.
|
|
- **`WAL_INDEX`** is the current write-ahead-log index.
|
|
|
|
<Tip>
|
|
|
|
Vault periodically persists the number of encryptions to support rotation. The
|
|
save operation has a 1 second timeout to limit performance impact when Vault is
|
|
under heavy load. If you use seal wrap, persisting encryptions involves the seal
|
|
backend, which means that some seals, like HSMs, may routinely take longer than
|
|
1 second to respond. You can override the save timeout by setting the
|
|
`VAULT_ENCRYPTION_COUNT_PERSIST_TIMEOUT` environment variable on your Vault
|
|
server to a larger value, such as "5s".
|
|
|
|
</Tip>
|