Rotate encryption key APIedit

[preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Rotate the encryption key for encrypted saved objects.

For the most up-to-date API details, refer to the open API specification.

If a saved object cannot be decrypted using the primary encryption key, then Kibana will attempt to decrypt it using the specified decryption-only keys. In most of the cases this overhead is negligible, but if you’re dealing with a large number of saved objects and experiencing performance issues, you may want to rotate the encryption key.

Bulk key rotation can consume a considerable amount of resources and hence only user with a superuser role can trigger it.

Requestedit

POST <kibana host>:<port>/api/encrypted_saved_objects/_rotate_key

Query parametersedit

type
(Optional, string) Limits encryption key rotation only to the saved objects with the specified type. By default, Kibana tries to rotate the encryption key for all saved object types that may contain encrypted attributes.
batch_size
(Optional, number) Specifies a maximum number of saved objects that Kibana can process in a single batch. Bulk key rotation is an iterative process since Kibana may not be able to fetch and process all required saved objects in one go and splits processing into consequent batches. By default, the batch size is 10000, which is also a maximum allowed value.

Response bodyedit

total
(number) Indicates the total number of all encrypted saved objects (optionally filtered by the requested type), regardless of the key Kibana used for encryption.
successful

(number) Indicates the total number of all encrypted saved objects (optionally filtered by the requested type), regardless of the key Kibana used for encryption.

In most cases, total will be greater than successful even if failed is zero. The reason is that Kibana may not need or may not be able to rotate encryption keys for all encrypted saved objects.

failed
(number) Indicates the number of the saved objects that were still encrypted with one of the old encryption keys that Kibana failed to re-encrypt with the primary key.

Response codeedit

200
Indicates a successful call.
400
Indicates that either query parameters are wrong or decryption-only keys aren’t configured.
429
Indicates that key rotation is already in progress.

Examplesedit

Encryption key rotation with default parametersedit

$ curl -X POST /api/encrypted_saved_objects/_rotate_key

The API returns the following:

{
  "total": 1000,
  "successful": 300,
  "failed": 0
}

The result indicates that the encryption key was successfully rotated for 300 out of 1000 saved objects with encrypted attributes, and 700 of the saved objects either didn’t require key rotation, or were encrypted with an unknown encryption key.

Encryption key rotation for the specific type with reduce batch sizeedit

Default parameters are optimized for speed. Change the parameters only when necessary. However, if you’re experiencing any issues with this API, you may want to decrease a batch size or rotate the encryption keys for the specific types only. In this case, you may need to run key rotation multiple times in a row.

In this example, key rotation is performed for all saved objects with the alert type in batches of 5000.

$ curl -X POST /api/encrypted_saved_objects/_rotate_key?type=alert&batch_size=5000

The API returns the following:

{
  "total": 100,
  "successful": 100,
  "failed": 0
}

The result indicates that the encryption key was successfully rotated for all 100 saved objects with the alert type.