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 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.
- Rekeying begins with a configured split and threshold for unseal keys:
- Vault receives the configured threshold of unseal keys.
- Vault generates and splits the new root key.
- Vault re-encrypts the internal encryption key with the new root key.
- Vault returns the new unseal keys.
- Rotation begins:
- Vault generates a new internal encryption key.
- Vault adds the new encryption key to an internal keyring.
- 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.
Related API endpoints
ConfigureKeyRotation - POST:/sys/rotate/config
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
recommends rotating keys before performing ~232 encryptions. By
default, Vault monitors the vault.barrier.estimated_encryptions
metric and
automatically rotates the backend encryption key before reaching 232
encryption operations.
You can approximate the vault.barrier.estimated_encryptions
metric with the
following sum:
where:
PUT_EVENTS
is thevault.barrier.put
telemetry metric.CREATION_EVENTS
is thevault.token.creation
metric wheretoken_type
isbatch
.MERKLE_FLUSH_EVENTS
is themerkle.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".