[7.x][Docs] Document Encrypted Saved Objects functionality. (#80867)

docs/api/saved-objects.asciidoc

@@ -28,6 +28,8 @@ The following saved objects APIs are available:
 
 * <<saved-objects-api-resolve-import-errors, Resolve import errors API>> to resolve errors from the import API
 
+* <<saved-objects-api-rotate-encryption-key, Rotate encryption key API>> to rotate the encryption key for encrypted saved objects
+
 include::saved-objects/get.asciidoc[]
 include::saved-objects/bulk_get.asciidoc[]
 include::saved-objects/find.asciidoc[]
@@ -38,3 +40,4 @@ include::saved-objects/delete.asciidoc[]
 include::saved-objects/export.asciidoc[]
 include::saved-objects/import.asciidoc[]
 include::saved-objects/resolve_import_errors.asciidoc[]
+include::saved-objects/rotate_encryption_key.asciidoc[]

docs/api/saved-objects/rotate_encryption_key.asciidoc

@@ -0,0 +1,110 @@
+[role="xpack"]
+[[saved-objects-api-rotate-encryption-key]]
+=== Rotate encryption key API
+++++
+<titleabbrev>Rotate encryption key</titleabbrev>
+++++
+
+experimental[] Rotate the encryption key for encrypted saved objects.
+
+If a saved object cannot be decrypted using the primary encryption key, then {kib} will attempt to decrypt it using the specified <<xpack-encryptedSavedObjects-keyRotation-decryptionOnlyKeys, 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.
+
+[IMPORTANT]
+============================================================================
+Bulk key rotation can consume a considerable amount of resources and hence only user with a `superuser` role can trigger it.
+============================================================================
+
+[[saved-objects-api-rotate-encryption-key-request]]
+==== Request
+
+`POST <kibana host>:<port>/api/encrypted_saved_objects/_rotate_key`
+
+[[saved-objects-api-rotate-encryption-key-request-query-params]]
+==== Query parameters
+
+`type`::
+(Optional, string) Limits encryption key rotation only to the saved objects with the specified type. By default, {kib} tries to rotate the encryption key for all saved object types that may contain encrypted attributes.
+
+`batchSize`::
+(Optional, number) Specifies a maximum number of saved objects that {kib} can process in a single batch. Bulk key rotation is an iterative process since {kib} 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.
+
+[[saved-objects-api-rotate-encryption-key-response-body]]
+==== Response body
+
+`total`::
+(number) Indicates the total number of _all_ encrypted saved objects (optionally filtered by the requested `type`), regardless of the key {kib} used for encryption.
+
+`successful`::
+(number) Indicates the total number of _all_ encrypted saved objects (optionally filtered by the requested `type`), regardless of the key {kib} used for encryption.
++
+NOTE: In most cases, `total` will be greater than `successful` even if `failed` is zero. The reason is that {kib} 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 {kib} failed to re-encrypt with the primary key.
+
+[[saved-objects-api-rotate-encryption-key-response-codes]]
+==== Response code
+
+`200`::
+Indicates a successful call.
+
+`400`::
+Indicates that either query parameters are wrong or <<xpack-encryptedSavedObjects-keyRotation-decryptionOnlyKeys, decryption-only keys>> aren't configured.
+
+`429`::
+Indicates that key rotation is already in progress.
+
+[[saved-objects-api-rotate-encryption-key-example]]
+==== Examples
+
+[[saved-objects-api-rotate-encryption-key-example-1]]
+===== Encryption key rotation with default parameters
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST /api/encrypted_saved_objects/_rotate_key
+--------------------------------------------------
+// KIBANA
+
+The API returns the following:
+
+[source,sh]
+--------------------------------------------------
+{
+  "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.
+
+[[saved-objects-api-rotate-encryption-key-example-2]]
+===== Encryption key rotation for the specific type with reduce batch size
+
+[IMPORTANT]
+============================================================================
+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.
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST /api/encrypted_saved_objects/_rotate_key?type=alert&batchSize=5000
+--------------------------------------------------
+// KIBANA
+
+The API returns the following:
+
+[source,sh]
+--------------------------------------------------
+{
+  "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.
+

docs/settings/security-settings.asciidoc

@@ -239,3 +239,26 @@ The format is a string of `<count>[ms\|s\|m\|h\|d\|w\|M\|Y]` (e.g. '20m', '24h',
 ============
 
 |===
+
+[float]
+[[security-encrypted-saved-objects-settings]]
+==== Encrypted saved objects settings
+
+These settings control the encryption of saved objects with sensitive data. For more details, refer to <<xpack-security-secure-saved-objects>>.
+
+[IMPORTANT]
+============
+In high-availability deployments, make sure you use the same encryption and decryption keys for all instances of {kib}. Although the keys can be specified in clear text in `kibana.yml`, it's recommended to store them securely in the <<secure-settings,{kib} Keystore>>.
+============
+
+[cols="2*<"]
+|===
+| [[xpack-encryptedSavedObjects-encryptionKey]] `xpack.encryptedSavedObjects.`
+`encryptionKey`
+| An arbitrary string of at least 32 characters that is used to encrypt sensitive properties of saved objects before they're stored in {es}. If not set, {kib} will generate a random key on startup, but certain features won't be available until you set the encryption key explicitly.
+
+| [[xpack-encryptedSavedObjects-keyRotation-decryptionOnlyKeys]] `xpack.encryptedSavedObjects.`
+`keyRotation.decryptionOnlyKeys`
+| An optional list of previously used encryption keys. Like <<xpack-encryptedSavedObjects-encryptionKey, `xpack.encryptedSavedObjects.encryptionKey`>>, these must be at least 32 characters in length. {kib} doesn't use these keys for encryption, but may still require them to decrypt some existing saved objects. Use this setting if you wish to change your encryption key, but don't want to lose access to saved objects that were previously encrypted with a different key.
+
+|===

docs/user/security/secure-saved-objects.asciidoc

@@ -0,0 +1,47 @@
+[role="xpack"]
+[[xpack-security-secure-saved-objects]]
+=== Secure saved objects
+
+{kib} stores entities such as dashboards, visualizations, alerts, actions, and advanced settings as saved objects, which are kept in a dedicated, internal {es} index. If such an object includes sensitive information, for example a PagerDuty integration key or email server credentials used by the alert action, {kib} encrypts it and makes sure it cannot be accidentally leaked or tampered with.
+
+Encrypting sensitive information means that a malicious party with access to the {kib} internal indices won't be able to extract that information without also knowing the encryption key.
+
+Example `kibana.yml`:
+
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.encryptedSavedObjects:
+  encryptionKey: "min-32-byte-long-strong-encryption-key"
+--------------------------------------------------------------------------------
+
+[IMPORTANT]
+============================================================================
+If you don't specify an encryption key, {kib} automatically generates a random key at startup. Every time you restart {kib}, it uses a new ephemeral encryption key and is unable to decrypt saved objects encrypted with another key. To prevent data loss, {kib} might disable features that rely on this encryption until you explicitly set an encryption key.
+============================================================================
+
+[[encryption-key-rotation]]
+==== Encryption key rotation
+
+Many policies and best practices stipulate that encryption keys should be periodically rotated to decrease the amount of content encrypted with one key and therefore limit the potential damage if the key is compromised. {kib} allows you to rotate encryption keys whenever there is a need.
+
+When you change an encryption key, be sure to keep the old one for some time. Although {kib} only uses a new encryption key to encrypt all new and updated data, it still may need the old one to decrypt data that was encrypted using the old key. It's possible to have multiple old keys used only for decryption. {kib} doesn't automatically re-encrypt existing saved objects with the new encryption key. Re-encryption only happens when you update existing object or use the <<saved-objects-api-rotate-encryption-key, rotate encryption key API>>.
+
+Here is how your `kibana.yml` might look if you use key rotation functionality:
+
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.encryptedSavedObjects:
+  encryptionKey: "min-32-byte-long-NEW-encryption-key" <1>
+  keyRotation:
+    decryptionOnlyKeys: ["min-32-byte-long-OLD#1-encryption-key", "min-32-byte-long-OLD#2-encryption-key"] <2>
+--------------------------------------------------------------------------------
+
+<1> The encryption key {kib} will use to encrypt all new or updated saved objects. This is known as the primary encryption key.
+<2> A list of encryption keys {kib} will try to use to decrypt existing saved objects if decryption with the primary encryption key isn't possible. These keys are known as the decryption-only or secondary encryption keys.
+
+[NOTE]
+============================================================================
+You might also leverage this functionality if multiple {kib} instances connected to the same {es} cluster use different encryption keys. In this case, you might have a mix of saved objects encrypted with different keys, and every {kib} instance can only deal with a specific subset of objects. To fix this, you must choose a single primary encryption key for `xpack.encryptedSavedObjects.encryptionKey`, move all other encryption keys to `xpack.encryptedSavedObjects.keyRotation.decryptionOnlyKeys`, and sync this configuration across all {kib} instances.
+============================================================================
+
+At some point, you might want to dispose of old encryption keys completely. Make sure there are no saved objects that {kib} encrypted with these encryption keys. You can use the <<saved-objects-api-rotate-encryption-key, rotate encryption key API>> to determine which existing saved objects require decryption-only keys and re-encrypt them with the primary key.

docs/user/security/securing-kibana.asciidoc

@@ -129,3 +129,4 @@ include::securing-communications/elasticsearch-mutual-tls.asciidoc[]
 include::audit-logging.asciidoc[]
 include::access-agreement.asciidoc[]
 include::session-management.asciidoc[]
+include::secure-saved-objects.asciidoc[]