diff --git a/changelog/10744.txt b/changelog/10744.txt new file mode 100644 index 000000000..e447cbf8f --- /dev/null +++ b/changelog/10744.txt @@ -0,0 +1,3 @@ +```release-note:improvement +core: Track barrier encryption count and automatically rotate after a large number of operations or on a schedule +``` diff --git a/website/content/api-docs/system/key-status.mdx b/website/content/api-docs/system/key-status.mdx index 918ced62b..89b513465 100644 --- a/website/content/api-docs/system/key-status.mdx +++ b/website/content/api-docs/system/key-status.mdx @@ -36,9 +36,12 @@ $ curl \ ```json { "term": 3, - "install_time": "2015-05-29T14:50:46.223692553-07:00" + "install_time": "2015-05-29T14:50:46.223692553-07:00", + "encryptions": 74718331 } ``` -The `term` parameter is the sequential key number, and `install_time` is the -time that encryption key was installed. +The `term` parameter is the sequential key number. `install_time` is the +time that encryption key was installed. `encryptions` is the estimated +number of encryptions made by the key including those on other cluster +nodes. diff --git a/website/content/api-docs/system/rotate-config.mdx b/website/content/api-docs/system/rotate-config.mdx new file mode 100644 index 000000000..ddece47aa --- /dev/null +++ b/website/content/api-docs/system/rotate-config.mdx @@ -0,0 +1,84 @@ +--- +layout: api +page_title: /sys/rotate/config - HTTP API +sidebar_title: /sys/rotate/config +description: The `/sys/rotate/config` endpoint is used to configure automatic key rotation. +--- + +# `/sys/rotate/config` + +The `/sys/rotate` endpoint is used to configure automatic key rotation. + +## Configure Automatic Key Rotation + +This endpoint configures the automatic rotation of the backend encryption key. By +default, the key is rotated after just under 4 billion encryptions, to satisfy the +recommendation of [NIST SP 800-38D](https://csrc.nist.gov/publications/detail/sp/800-38d/final). +One can configure rotations after fewer encryptions or on a time based schedule. + +## Create or Update the Auto Rotation Configuration + +| Method | Path | +| :------ | :------------------- | +| `POST` | `/sys/rotate/config` | + +### Parameters + +- `max_operations` `(int: 3865470566)` - Specify the limit of encryptions after which + the key will be automatically rotated. The number cannot be higher than + the default. Specifing 0 resets max_operations to the default. +- `interval` `(string: "") - If set, the age of the active key at which an + automatic rotation is triggered. Specified as a Go duration string (e.g. 4320h) +- `enabled` `(bool: true)` - If set to false, automatic rotations will not + be performed. Tracking of encryption counts will continue. + +### Sample Payload + +```json +{ + "max_operations": 2000000000, + "interval": "4320h" +} +``` + +### Sample Request + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ..." \ + --data @payload.json \ + http://127.0.0.1:8200/v1/sys/rotate/config +``` + +## Get the Auto Rotation Configuration + +| Method | Path | +| :----- | :------------------- | +| `GET` | `/sys/rotate/config` | + +### Sample Request + +```shell-session +$ curl \ + --request GET \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/sys/rotate/config +``` + +### Sample Response + +```json +{ + "request_id": "f3d91b4a-69bf-4aaf-b928-df7a5486c130", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "max_operations": 2000000000, + "interval": "4320h", + "enabled": true + }, + "warnings": null +} +``` diff --git a/website/content/docs/upgrading/upgrade-to-1.7.0.mdx b/website/content/docs/upgrading/upgrade-to-1.7.0.mdx new file mode 100644 index 000000000..7bf1677c2 --- /dev/null +++ b/website/content/docs/upgrading/upgrade-to-1.7.0.mdx @@ -0,0 +1,22 @@ +--- +layout: docs +page_title: Upgrading to Vault 1.7.0 - Guides +sidebar_title: Upgrade to 1.7.0 +description: |- + This page contains the list of deprecations and important or breaking changes + for Vault 1.7..0. Please read it carefully. +--- + +# Overview + +This page contains the list of deprecations and important or breaking changes +for Vault 1.7.0 compared to 1.6. Please read it carefully. + +## Barrier Key Auto-Rotation + +If your Vault installation is at least a year old, the barrier key will be +automatically rotated once, and then subsequently will be rotated per the +settings in the new `sys/rotate/config` endpoint. This is a precaution to +ensure the number of encryptions performed by the barrier key is fewer than that +rrecommended by +[NIST SP 800-38D](https://csrc.nist.gov/publications/detail/sp/800-38d/final). \ No newline at end of file diff --git a/website/data/api-navigation.js b/website/data/api-navigation.js index fb3526eb5..52c01c551 100644 --- a/website/data/api-navigation.js +++ b/website/data/api-navigation.js @@ -144,6 +144,7 @@ export default [ content: ['replication-performance', 'replication-dr'], }, 'rotate', + 'rotate-config', 'seal', 'seal-status', 'sealwrap-rewrap',