---
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).

![Key Rotate](/img/vault-key-rotate.png)

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>