mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-06 22:57:02 +02:00
9f2c4353ae
* Create placeholders for missing metric * update metric info and rewrite rotation doc * Deal with erroneous content error
101 lines
3.8 KiB
Plaintext
101 lines
3.8 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Key Rotation
|
|
description: Learn about the details of key rotation within Vault.
|
|
---
|
|
|
|
# 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>
|