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.

1. Rekeying begins with a configured split and threshold for unseal keys:
   1. Vault receives the configured threshold of unseal keys.
   2. Vault generates and splits the new root key.
   3. Vault re-encrypts the internal encryption key with the new root key.
   4. Vault returns the new unseal keys.
2. Rotation begins:
   1. Vault generates a new internal encryption key.
   2. Vault adds the new encryption key to an internal keyring.
   3. 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.

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 ~2³² encryptions. By default, Vault monitors the vault.barrier.estimated_encryptions metric and automatically rotates the backend encryption key before reaching 2³² encryption operations.

You can approximate the vault.barrier.estimated_encryptions metric with the following sum:

ESTIMATED_OPS = PUT_EVENTS + CREATE_EVENTS + MERKLE_FLUSH_EVENTS + WAL_INDEX

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.