docs: add barrier key auto-rotation to internals/rotation (#12149)

This functionality was introduced in Vault 1.7.0 and is documented in api-docs/system/rotate-config
This commit is contained in:
mickael-hc 2021-08-03 18:52:24 -04:00 committed by GitHub
parent 87fe00c775
commit 28cb68ba11
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -54,20 +54,22 @@ for a few minutes enabling standby instances to do a periodic check for upgrades
This allows standby instances to update their keys and stay in-sync with the active Vault
without requiring operators to perform another unseal.
The `rotate/config` endpoint is used to configure the number of operations or time interval
between automatic rotations of the backend encryption key.
## NIST Rotation Guidance
Periodic rotation of the encryption keys is recommended, even in the absence of
compromise. Due to the nature of the AES-256-GCM encryption used, keys should be
rotated before approximately 2<sup>32</sup> encryptions have been performed, following
the guidelines of NIST publication 800-38D. Operators can estimate the number
of encryptions by summing the following:
the guidelines of NIST publication 800-38D.
As of Vault 1.7, Vault will automatically rotate the backend encryption key
prior to reaching 2<sup>32</sup> encryption operations by default.
Operators can estimate the number of encryptions by summing the following:
- The `vault.barrier.put` telemetry metric.
- The `vault.token.creation` metric where the `token_type` label is `batch`.
- The `merkle.flushDirty.num_pages` metric.
- The WAL index.
The simplest strategy may be to use those metrics to determine a frequency of
rotation and make that part of the operational process. For example, if one
determines that the estimated rate is 40 million operations per day, then
rotating the key every three months is sufficient.
- The WAL index.