[Docs] Document Encrypted Saved Objects functionality. #80183

azasypkin · 2020-10-12T16:16:26Z

Document Encrypted Saved Objects functionality.

Preview:

azasypkin · 2020-10-13T09:28:39Z

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

@@ -0,0 +1,90 @@
+[role="xpack"]
+[[xpack-security-secure-saved-objects]]
+=== Secure Saved Objects


note: didn't want to be too specific and say Encrypt, used more generic Secure word....

azasypkin · 2020-10-13T09:29:31Z

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

+[[xpack-security-secure-saved-objects]]
+=== Secure Saved Objects
+
+In {kib} you usually deal with dashboards, visualizations, alerts, actions, advanced settings, spaces etc. These are so called *Saved Objects* that {kib} stores in a dedicated internal {es} index. If such an object includes any sensitive information, for example a PagerDuty’s 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. Moreover, {kib} records any access attempt to such sensitive information in the audit logs. 


note: That's the shortest introduction to Saved Objects I could come up with, happy to get better ideas! 🙈

I like this! I think we can do without the audit log reference. We don't document this today, and what we end up logging in the new audit logger will probably differ from what currently exists.

Suggested change

In {kib} you usually deal with dashboards, visualizations, alerts, actions, advanced settings, spaces etc. These are so called *Saved Objects* that {kib} stores in a dedicated internal {es} index. If such an object includes any sensitive information, for example a PagerDuty’s 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. Moreover, {kib} records any access attempt to such sensitive information in the audit logs.

{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 any sensitive information, for example a PagerDuty’s 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.

azasypkin · 2020-10-13T09:30:02Z

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

+
+<1> {kib} will rotate encryption key only for the Saved Objects with the `alert` type in batches of 5000 objects.
+
+For the time being if you specify decryption-only keys {kib} may try to use them all if it cannot decrypt the Saved Object using the primary encryption key. In most of the cases this overhead is negligible, but if you're constantly dealing with the thousands of the Saved Objects that are encrypted and experiencing performance issues you may want to try to rotate encryption key for those objects.


note: I'm torn on this one, maybe it's more confusing than useful?

I feel like this would be better suited at the top of the API doc (once extracted, see other comment). This does a nice job of explaining why you might want to use this API, so I think it's worthwhile to keep in.

Yep, moved, thanks!

elasticmachine · 2020-10-13T09:31:01Z

Pinging @elastic/kibana-security (Team:Security)

legrego

First pass through - I think this is off to a great start!
All of my suggestions are subject to revision by the docs team 😄

legrego · 2020-10-13T15:43:52Z

docs/settings/security-settings.asciidoc

+[[security-encrypted-saved-objects-settings]]
+==== Encrypted Saved Objects settings
+
+You can configure the following settings in the `kibana.yml` file. For more details see <<xpack-security-secure-saved-objects>>.


Suggested change

You can configure the following settings in the `kibana.yml` file. For more details see <<xpack-security-secure-saved-objects>>.

These settings control the encryption of saved objects with sensitive data. For more details see <<xpack-security-secure-saved-objects>>.

legrego · 2020-10-13T15:45:02Z

docs/settings/security-settings.asciidoc

+|===
+| [[xpack-encryptedSavedObjects-encryptionKey]] `xpack.encryptedSavedObjects.`
+`encryptionKey`
+| An arbitrary string of 32 characters or more that is used to encrypt sensitive properties of the Saved Objects before they're stored in {es}. If not set, {kib} will generate a random key on startup, but certain {kib} functionality won't be available until you set the encryption key explicitly.


Suggested change

| An arbitrary string of 32 characters or more that is used to encrypt sensitive properties of the Saved Objects before they're stored in {es}. If not set, {kib} will generate a random key on startup, but certain {kib} functionality won't be available until you set the encryption key explicitly.

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

legrego · 2020-10-13T15:48:05Z

docs/settings/security-settings.asciidoc

+
+| `xpack.encryptedSavedObjects.`
+`keyRotation.decryptionOnlyKeys`
+| An optional list of arbitrary strings of 32 characters or more that were used as <<xpack-encryptedSavedObjects-encryptionKey, `xpack.encryptedSavedObjects.encryptionKey`>> previously. As the name implies {kib} doesn't use these keys for encryption, but may still require them to decrypt some existing Saved Objects.


Suggested change

| An optional list of arbitrary strings of 32 characters or more that were used as <<xpack-encryptedSavedObjects-encryptionKey, `xpack.encryptedSavedObjects.encryptionKey`>> previously. As the name implies {kib} doesn't use these keys for encryption, but may still require them to decrypt some existing Saved Objects.

| An optional list of previously used encryption keys. Like <<xpack-encryptedSavedObjects-encryptionKey, `xpack.encryptedSavedObjects.encryptionKey`>>, these must be at least 32 characters in length. As the name implies {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.

legrego · 2020-10-13T15:51:14Z

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

+[[xpack-security-secure-saved-objects]]
+=== Secure Saved Objects
+
+In {kib} you usually deal with dashboards, visualizations, alerts, actions, advanced settings, spaces etc. These are so called *Saved Objects* that {kib} stores in a dedicated internal {es} index. If such an object includes any sensitive information, for example a PagerDuty’s 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. Moreover, {kib} records any access attempt to such sensitive information in the audit logs. 


I like this! I think we can do without the audit log reference. We don't document this today, and what we end up logging in the new audit logger will probably differ from what currently exists.

Suggested change

In {kib} you usually deal with dashboards, visualizations, alerts, actions, advanced settings, spaces etc. These are so called *Saved Objects* that {kib} stores in a dedicated internal {es} index. If such an object includes any sensitive information, for example a PagerDuty’s 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. Moreover, {kib} records any access attempt to such sensitive information in the audit logs.

{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 any sensitive information, for example a PagerDuty’s 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.

legrego · 2020-10-13T15:54:21Z

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

+
+In {kib} you usually deal with dashboards, visualizations, alerts, actions, advanced settings, spaces etc. These are so called *Saved Objects* that {kib} stores in a dedicated internal {es} index. If such an object includes any sensitive information, for example a PagerDuty’s 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. Moreover, {kib} records any access attempt to such sensitive information in the audit logs. 
+
+Having sensitive information encrypted means that even if a malicious party can somehow get access to the {kib} internal indices, for example through improperly secured backup, they won't be able to extract that information without knowing an encryption key usually stored separately in a keystore or a configuration file. That's why it's critical to use a cryptographically strong encryption key and keep it safe.


Suggested change

Having sensitive information encrypted means that even if a malicious party can somehow get access to the {kib} internal indices, for example through improperly secured backup, they won't be able to extract that information without knowing an encryption key usually stored separately in a keystore or a configuration file. That's why it's critical to use a cryptographically strong encryption key and keep it safe.

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. That's why it's critical to use a cryptographically strong encryption key and keep it safe.

Here we suggest a cryptographically strong encryption key, but the settings page says that the key can be an arbitrary string of 32 characters or more. I know we're working on a tool for this, but maybe we can have consistent language between the two? Is there any guidance we should add on how to generate a strong key?

Yeah, I think I'll just remove that sentence. We should either include that everywhere (including reporting and session keys) or don't mention at all. But I don't want to waste our time on that since I hope we will eventually migrate to a single admin-configurable master key and that one will have a proper doc section.

legrego · 2020-10-13T15:56:06Z

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

+
+[IMPORTANT]
+============================================================================
+If you don't specify encryption key {kib} will generate a random one automatically at startup time. That means every time you restart {kib} it will use a new ephemeral encryption key and won't be able to decrypt Saved Objects encrypted with another key. To prevent this {kib} plugins may not allow you to perform certain actions until you explicitly set an encryption key.


Suggested change

If you don't specify encryption key {kib} will generate a random one automatically at startup time. That means every time you restart {kib} it will use a new ephemeral encryption key and won't be able to decrypt Saved Objects encrypted with another key. To prevent this {kib} plugins may not allow you to perform certain actions until you explicitly set an encryption key.

If you don't specify encryption key {kib} will generate a random one automatically at startup time. That means every time you restart {kib} it will use a new ephemeral encryption key and won't be able to decrypt Saved Objects encrypted with another key. To prevent data loss, {kib} may disable features which rely on this encryption until you explicitly set an encryption key.

legrego · 2020-10-13T15:59:21Z

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

+
+Many policies and best practices stipulate that encryption keys should be periodically rotated to decrease the amount of content encrypted with one key and hence limit the potential damage in case the key is compromised. {kib} allows you to rotate encryption keys whenever there is a need. 
+
+As a rule of thumb, when you change an encryption key you still keep the old one for some time. While {kib} will only use a new encryption key to encrypt all new and updated data it still may need to know the old one to decrypt data that was encrypted using that old key. Moreover, it's perfectly possible to have multiple old keys used only for decryption. It's worth noting that {kib} doesn't re-encrypt existing Saved Objects with the new encryption key automatically, re-encryption only happens when you update existing object or use bulk key rotation API explained later on.


or use bulk key rotation API explained later on.

Can we add an anchor to the API explanation here instead of saying it's explained later on?

legrego · 2020-10-13T16:19:10Z

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

+    decryptionOnlyKeys: ["min-32-byte-long-OLD#1-encryption-key", "min-32-byte-long-OLD#2-encryption-key"] <2>
+--------------------------------------------------------------------------------
+
+<1> Encryption key {kib} will use to encrypt all new or updated Saved Objects, known as a primary encryption key.


Suggested change

<1> Encryption key {kib} will use to encrypt all new or updated Saved Objects, known as a primary encryption key.

<1> Encryption key {kib} will use to encrypt all new or updated Saved Objects, known as the primary encryption key.

legrego · 2020-10-13T16:25:31Z

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

+============================================================================
+
+At some point you may want to dispose old encryption keys completely, but before that you should make sure there are no Saved Objects left that {kib} encrypted with the encryption key you're going to dispose. You can use bulk key rotation API for that purpose. It will figure out which existing Saved Objects still require decryption-only keys and re-encrypt them with the primary key. It may take a while if you have lots of such Saved Objects:
+


What do you think about extracting this out to the Saved Objects API docs, and then link to it from here?

I think we should also update this to match the format of the other REST API docs (example)

Yeah, that's a great idea! Will do.

legrego · 2020-10-13T16:27:12Z

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

+
+<1> {kib} will rotate encryption key only for the Saved Objects with the `alert` type in batches of 5000 objects.
+
+For the time being if you specify decryption-only keys {kib} may try to use them all if it cannot decrypt the Saved Object using the primary encryption key. In most of the cases this overhead is negligible, but if you're constantly dealing with the thousands of the Saved Objects that are encrypted and experiencing performance issues you may want to try to rotate encryption key for those objects.


I feel like this would be better suited at the top of the API doc (once extracted, see other comment). This does a nice job of explaining why you might want to use this API, so I think it's worthwhile to keep in.

…for the consistency sake.

elasticmachine · 2020-10-14T10:36:40Z

Pinging @elastic/kibana-docs (Team:Docs)

azasypkin · 2020-10-14T10:37:25Z

Thanks for review @legrego, should be ready for another pass!

legrego

I think this looks great! Feel free to ignore my revisions here in favor of the docs team so that you don't have to make too many repetitive changes

legrego · 2020-10-14T12:51:39Z

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 encryption key for the saved objects with encrypted attributes


Your text is technically more accurate, but I think this is a little easier to read

Suggested change

* <<saved-objects-api-rotate-encryption-key, Rotate encryption key API>> to rotate encryption key for the saved objects with encrypted attributes

* <<saved-objects-api-rotate-encryption-key, Rotate encryption key API>> to rotate encryption key for encrypted saved objects

How about:

to rotate the encryption key...

or to rotate encryption keys...

legrego · 2020-10-14T12:53:45Z

docs/api/saved-objects/rotate_encryption_key.asciidoc

+<titleabbrev>Rotate encryption key</titleabbrev>
++++
+
+experimental[] Rotate encryption key for the saved objects with encrypted attributes.


Suggested change

experimental[] Rotate encryption key for the saved objects with encrypted attributes.

experimental[] Rotate encryption key for encrypted saved objects.

legrego · 2020-10-14T12:56:16Z

docs/api/saved-objects/rotate_encryption_key.asciidoc

+
+experimental[] Rotate encryption key for the saved objects with encrypted attributes.
+
+For the time being if you specify <<xpack-encryptedSavedObjects-keyRotation-decryptionOnlyKeys, decryption-only keys>> {kib} may try to use them all if it cannot decrypt the saved object using the primary encryption key. In most of the cases this overhead is negligible, but if you're constantly dealing with the thousands of the saved objects that are encrypted and experiencing performance issues you may want to try to rotate encryption key for those objects.


Suggested change

For the time being if you specify <<xpack-encryptedSavedObjects-keyRotation-decryptionOnlyKeys, decryption-only keys>> {kib} may try to use them all if it cannot decrypt the saved object using the primary encryption key. In most of the cases this overhead is negligible, but if you're constantly dealing with the thousands of the saved objects that are encrypted and experiencing performance issues you may want to try to rotate encryption key for those 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.

👍 The funny thing that the Webstorm built-in "spell checker" didn't like a large number of when I used initially, maybe it's too casual for the tech docs (I actually like a large number better because it's how it would be correct to write in my native language as well) 🙈

legrego · 2020-10-14T12:59:04Z

docs/api/saved-objects/rotate_encryption_key.asciidoc

+==== Response body
+
+`total`::
+(number) Indicates the total number of _all_ saved objects with the encrypted attributes, irrespective to the key {kib} used for encryption.


Suggested change

(number) Indicates the total number of _all_ saved objects with the encrypted attributes, irrespective to the key {kib} used for encryption.

(number) Indicates the total number of _all_ encrypted saved objects (optionally filtered by the requested `type`), regardless of the key {kib} used for encryption.

Ugh, it seems I forgot to update this one, will do!

KOTungseth · 2020-10-14T16:20:46Z

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 encryption key for the saved objects with encrypted attributes


How about:

to rotate the encryption key...

or to rotate encryption keys...

KOTungseth · 2020-10-14T16:21:56Z

docs/api/saved-objects/rotate_encryption_key.asciidoc

+==== Query parameters
+
+`type`::
+(Optional, string) Limits encryption key rotation only to the saved objects with the specified type. By default, {kib} will try to rotate encryption key for all saved object types that may contain encrypted attributes.


Suggested change

(Optional, string) Limits encryption key rotation only to the saved objects with the specified type. By default, {kib} will try to rotate encryption key for all saved object types that may contain encrypted attributes.

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

KOTungseth · 2020-10-14T16:22:29Z

docs/api/saved-objects/rotate_encryption_key.asciidoc

+(Optional, string) Limits encryption key rotation only to the saved objects with the specified type. By default, {kib} will try to rotate 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 hence splits processing into consequent batches. By default, batch size is 10000 which is also a maximum allowed value.


Suggested change

(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 hence splits processing into consequent batches. By default, batch size is 10000 which is also a maximum allowed value.

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

KOTungseth · 2020-10-14T16:23:21Z

docs/api/saved-objects/rotate_encryption_key.asciidoc

+`successful`::
+(number) Indicates the number of the saved objects that were still encrypted with one of the old encryption keys and that {kib} successfully re-encrypted with the primary key.
+
+NOTE: In most of the 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 key for all saved objects with the encrypted attributes.


Suggested change

NOTE: In most of the 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 key for all saved objects with the encrypted attributes.

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 saved objects with the encrypted attributes.

KOTungseth · 2020-10-14T16:24:07Z

docs/api/saved-objects/rotate_encryption_key.asciidoc

+}
+--------------------------------------------------
+
+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 unknown encryption key.


Suggested change

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 unknown encryption key.

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.

KOTungseth · 2020-10-14T16:25:51Z

docs/api/saved-objects/rotate_encryption_key.asciidoc

+
+[IMPORTANT]
+============================================================================
+We optimized default parameters for speed and don't expect you to change any of those without a strong need. However, if you're experiencing any issues with this API you may want to decrease a batch size or rotate encryption key for the specific types only. In this case you may need to run key rotation multiple times in a row.


Suggested change

We optimized default parameters for speed and don't expect you to change any of those without a strong need. However, if you're experiencing any issues with this API you may want to decrease a batch size or rotate encryption key for the specific types only. In this case you may need to run key rotation multiple times in a row.

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.

KOTungseth · 2020-10-14T16:26:11Z

docs/api/saved-objects/rotate_encryption_key.asciidoc

+We optimized default parameters for speed and don't expect you to change any of those without a strong need. However, if you're experiencing any issues with this API you may want to decrease a batch size or rotate encryption key for the specific types only. In this case you may need to run key rotation multiple times in a row.
+============================================================================
+
+In this example we perform key rotation for all saved objects with the `alert` type in batches of 5000.


Suggested change

In this example we perform key rotation for all saved objects with the `alert` type in batches of 5000.

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

Thanks! Was trying to fight passive voice with we and {kib} were possible :)

KOTungseth · 2020-10-14T16:26:35Z

docs/settings/security-settings.asciidoc

+[[security-encrypted-saved-objects-settings]]
+==== Encrypted saved objects settings
+
+These settings control the encryption of saved objects with sensitive data. For more details see <<xpack-security-secure-saved-objects>>.


Suggested change

These settings control the encryption of saved objects with sensitive data. For more details see <<xpack-security-secure-saved-objects>>.

These settings control the encryption of saved objects with sensitive data. For more details, refer to <<xpack-security-secure-saved-objects>>.

KOTungseth · 2020-10-14T16:26:51Z

docs/settings/security-settings.asciidoc

+
+[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>>.


Suggested change

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

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

KOTungseth · 2020-10-14T16:27:35Z

docs/settings/security-settings.asciidoc

+
+| [[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. As the name implies {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.


Suggested change

| An optional list of previously used encryption keys. Like <<xpack-encryptedSavedObjects-encryptionKey, `xpack.encryptedSavedObjects.encryptionKey`>>, these must be at least 32 characters in length. As the name implies {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.

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

gchaps · 2020-10-14T21:52:58Z

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

+[[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 any sensitive information, for example a PagerDuty’s 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.


Suggested change

{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 any sensitive information, for example a PagerDuty’s 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.

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

gchaps · 2020-10-14T21:54:30Z

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

+
+Example `kibana.yml`:
+
+[IMPORTANT]


Move this note below the code box.

gchaps · 2020-10-14T21:56:53Z

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

+
+[IMPORTANT]
+============================================================================
+If you don't specify encryption key {kib} will generate a random one automatically at startup time. That means every time you restart {kib} it will use a new ephemeral encryption key and won't be able to decrypt saved objects encrypted with another key. To prevent data loss, {kib} may disable features which rely on this encryption until you explicitly set an encryption key.


Suggested change

If you don't specify encryption key {kib} will generate a random one automatically at startup time. That means every time you restart {kib} it will use a new ephemeral encryption key and won't be able to decrypt saved objects encrypted with another key. To prevent data loss, {kib} may disable features which rely on this encryption until you explicitly set an encryption key.

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.

gchaps · 2020-10-14T21:59:41Z

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

+[[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 hence limit the potential damage in case the key is compromised. {kib} allows you to rotate encryption keys whenever there is a need. 


Suggested change

Many policies and best practices stipulate that encryption keys should be periodically rotated to decrease the amount of content encrypted with one key and hence limit the potential damage in case the key is compromised. {kib} allows you to rotate encryption keys whenever there is a need.

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.

gchaps · 2020-10-14T22:40:50Z

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

+
+Many policies and best practices stipulate that encryption keys should be periodically rotated to decrease the amount of content encrypted with one key and hence limit the potential damage in case the key is compromised. {kib} allows you to rotate encryption keys whenever there is a need. 
+
+As a rule of thumb, when you change an encryption key you still keep the old one for some time. While {kib} will only use a new encryption key to encrypt all new and updated data it still may need to know the old one to decrypt data that was encrypted using that old key. Moreover, it's perfectly possible to have multiple old keys used only for decryption. It's worth noting that {kib} doesn't re-encrypt existing saved objects with the new encryption key automatically, re-encryption only happens when you update existing object or use <<saved-objects-api-rotate-encryption-key, Rotate encryption key API>>.


Suggested change

As a rule of thumb, when you change an encryption key you still keep the old one for some time. While {kib} will only use a new encryption key to encrypt all new and updated data it still may need to know the old one to decrypt data that was encrypted using that old key. Moreover, it's perfectly possible to have multiple old keys used only for decryption. It's worth noting that {kib} doesn't re-encrypt existing saved objects with the new encryption key automatically, re-encryption only happens when you update existing object or use <<saved-objects-api-rotate-encryption-key, Rotate encryption key API>>.

When you change an encryption key, 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 objects or use the <<saved-objects-api-rotate-encryption-key, rotate encryption key API>>.

As a rule of thumb, when you change an encryption key you still keep the old one for some time. ---> When you change an encryption key, keep the old one for some time. this one is a bit tricky, we don't want to force/recommend and be responsible for that decision, we just say it's usually done like this. But there could be cases when encryption key leaks, data encrypted with it was tampered with something malicious and users really don't want these objects to be decrypted and used for whatever purpose in production. That means old keys should just be disposed immediately. We cannot also call this out specifically since their Security team should know what would be appropriate in their particular case.

@gchaps can you please suggest the appropriate language/tone for this?

This makes the sentence stronger:

When you change an encryption key, be sure to keep the old one for some time.

gchaps · 2020-10-14T22:45:16Z

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

+
+As a rule of thumb, when you change an encryption key you still keep the old one for some time. While {kib} will only use a new encryption key to encrypt all new and updated data it still may need to know the old one to decrypt data that was encrypted using that old key. Moreover, it's perfectly possible to have multiple old keys used only for decryption. It's worth noting that {kib} doesn't re-encrypt existing saved objects with the new encryption key automatically, re-encryption only happens when you update existing object or use <<saved-objects-api-rotate-encryption-key, Rotate encryption key API>>.
+
+Here is how your `kibana.yml` can look like if you want to use key rotation functionality:


Suggested change

Here is how your `kibana.yml` can look like if you want to use key rotation functionality:

Here is how your `kibana.yml` might look if you use key rotation functionality:

gchaps · 2020-10-14T22:46:28Z

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

+    decryptionOnlyKeys: ["min-32-byte-long-OLD#1-encryption-key", "min-32-byte-long-OLD#2-encryption-key"] <2>
+--------------------------------------------------------------------------------
+
+<1> Encryption key {kib} will use to encrypt all new or updated saved objects, known as the primary encryption key.


Suggested change

<1> Encryption key {kib} will use to encrypt all new or updated saved objects, known as the primary encryption key.

<1> The encryption key {kib} will use to encrypt all new or updated saved objects. This is known as the primary encryption key.

gchaps · 2020-10-14T22:48:12Z

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

+--------------------------------------------------------------------------------
+
+<1> Encryption key {kib} will use to encrypt all new or updated saved objects, known as the primary encryption key.
+<2> A list of encryption keys {kib} will try to use only to decrypt existing saved objects if decryption with the primary encryption key isn't possible, known as decryption-only or secondary encryption keys.


Suggested change

<2> A list of encryption keys {kib} will try to use only to decrypt existing saved objects if decryption with the primary encryption key isn't possible, known as decryption-only or secondary encryption keys.

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

gchaps · 2020-10-14T22:51:29Z

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

+
+[NOTE]
+============================================================================
+You may also leverage this functionality if, by mistake, you ended up with multiple {kib} instances connected to the same {es} cluster that use different encryption keys. In this case you may have a mix of saved objects encrypted with different keys and every {kib} instance can deal only with a specific subset of objects. To fix this you'll need to 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.


Suggested change

You may also leverage this functionality if, by mistake, you ended up with multiple {kib} instances connected to the same {es} cluster that use different encryption keys. In this case you may have a mix of saved objects encrypted with different keys and every {kib} instance can deal only with a specific subset of objects. To fix this you'll need to 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.

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.

gchaps · 2020-10-14T22:56:36Z

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

+You may also leverage this functionality if, by mistake, you ended up with multiple {kib} instances connected to the same {es} cluster that use different encryption keys. In this case you may have a mix of saved objects encrypted with different keys and every {kib} instance can deal only with a specific subset of objects. To fix this you'll need to 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 may want to dispose old encryption keys completely, but before that you should make sure there are no saved objects left that {kib} encrypted with the encryption key you're going to dispose. You can use <<saved-objects-api-rotate-encryption-key, Rotate encryption key API>> for that purpose. It will figure out which existing saved objects still require decryption-only keys and re-encrypt them with the primary key.


Suggested change

At some point you may want to dispose old encryption keys completely, but before that you should make sure there are no saved objects left that {kib} encrypted with the encryption key you're going to dispose. You can use <<saved-objects-api-rotate-encryption-key, Rotate encryption key API>> for that purpose. It will figure out which existing saved objects still require decryption-only keys and re-encrypt them with the primary key.

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.

azasypkin · 2020-10-15T09:05:32Z

Thanks for the great feedback @legrego @KOTungseth @gchaps! PR should be ready for another pass.

@gchaps I've left one question for you, would you mind taking a look?

gchaps

Found one missing comma, but other than that, the text I reviewed LGTM.

gchaps · 2020-10-15T16:20:12Z

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

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


Suggested change

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.

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.

Suggested change

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.

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.

legrego

LGTM!

azasypkin · 2020-10-16T16:27:34Z

7.10/7.10.0: 5f340ab
7.x/7.11.0: a50e8c9

* master: (43 commits) [ML] Transforms: Fix tab ids for expanded row. (elastic#80666) server logs config paths to use for runner (elastic#52980) Fix audit logger logging to console even when disabled (elastic#80928) skip flaky suite (elastic#80929) Added Enterprise Search config to kibana-docker (elastic#80872) skip flaky suite (elastic#80914) [keystore_cli] parse values as JSON before adding to keystore (elastic#80848) [Ingest Manager] Fix for comparing versions with -SNAPSHOT suffix (elastic#80742) ECS audit logging (elastic#74640) [Uptime] Add client-side unit tests for remaining synthetics code (elastic#80215) [Security_Solution][Resolver] Promote z-index on node labels (elastic#80854) Move renderHeaderActions back into mount useEffect + update tests (elastic#80861) [Reporting] Document Network Policy configuration (elastic#80431) [Reporting] Add contextual documentation for CSV Max Bytes setting (elastic#80782) Add catch for Enterprise Search sending back a 401 response instead of redirect (elastic#80757) [Actions] Back Button on Add Connector Flyout (elastic#80160) removing `kibana_datatable` in favor of `datatable` (elastic#80548) [Alerting UI] Updating 'Add new' wording (elastic#80509) [Docs] Document Encrypted Saved Objects functionality. (elastic#80183) [Discover] fix auto-refresh (elastic#80635) ...

* master: (23 commits) [ML] Transforms: Fix tab ids for expanded row. (elastic#80666) server logs config paths to use for runner (elastic#52980) Fix audit logger logging to console even when disabled (elastic#80928) skip flaky suite (elastic#80929) Added Enterprise Search config to kibana-docker (elastic#80872) skip flaky suite (elastic#80914) [keystore_cli] parse values as JSON before adding to keystore (elastic#80848) [Ingest Manager] Fix for comparing versions with -SNAPSHOT suffix (elastic#80742) ECS audit logging (elastic#74640) [Uptime] Add client-side unit tests for remaining synthetics code (elastic#80215) [Security_Solution][Resolver] Promote z-index on node labels (elastic#80854) Move renderHeaderActions back into mount useEffect + update tests (elastic#80861) [Reporting] Document Network Policy configuration (elastic#80431) [Reporting] Add contextual documentation for CSV Max Bytes setting (elastic#80782) Add catch for Enterprise Search sending back a 401 response instead of redirect (elastic#80757) [Actions] Back Button on Add Connector Flyout (elastic#80160) removing `kibana_datatable` in favor of `datatable` (elastic#80548) [Alerting UI] Updating 'Add new' wording (elastic#80509) [Docs] Document Encrypted Saved Objects functionality. (elastic#80183) [Discover] fix auto-refresh (elastic#80635) ...

azasypkin added Team:Security Team focused on: Auth, Users, Roles, Spaces, Audit Logging, and more! release_note:skip Skip the PR/issue when compiling release notes v7.10.0 docs labels Oct 12, 2020

[Docs] Document Encrypted Saved Objects functionality.

569b864

azasypkin force-pushed the issue-xxx-doc-eso branch from 07b6e01 to 569b864 Compare October 13, 2020 09:23

azasypkin commented Oct 13, 2020

View reviewed changes

azasypkin marked this pull request as ready for review October 13, 2020 09:30

azasypkin requested a review from a team October 13, 2020 09:31

legrego reviewed Oct 13, 2020

View reviewed changes

azasypkin added 3 commits October 14, 2020 08:16

Merge branch 'master' into issue-xxx-doc-eso

874bf89

Review#1: handle review feedback, use lower case for saved objects …

b144d88

…for the consistency sake.

Review#1: one more nit.

0f77c6d

azasypkin added the Team:Docs label Oct 14, 2020

Mark Rotate encryption key API as xpack only.

ee76d9b

azasypkin requested a review from a team October 14, 2020 12:58

legrego reviewed Oct 14, 2020

View reviewed changes

KOTungseth reviewed Oct 14, 2020

View reviewed changes

gchaps reviewed Oct 14, 2020

View reviewed changes

azasypkin added 2 commits October 15, 2020 09:21

Merge branch 'master' into issue-xxx-doc-eso

e71ff98

Review#2: improve docs.

9ee2303

azasypkin requested review from legrego, gchaps and KOTungseth October 15, 2020 09:05

azasypkin mentioned this pull request Oct 15, 2020

Don't generate xpack.encryptedSavedObjects.encryptionKey #79943

Closed

gchaps approved these changes Oct 15, 2020

View reviewed changes

azasypkin added 2 commits October 16, 2020 07:46

Merge branch 'master' into issue-xxx-doc-eso

4fd10d8

Review#3: improve docs.

6c5213c

legrego approved these changes Oct 16, 2020

View reviewed changes

azasypkin merged commit d4530e1 into elastic:master Oct 16, 2020

azasypkin deleted the issue-xxx-doc-eso branch October 16, 2020 16:16

azasypkin added v7.11.0 v8.0.0 labels Oct 16, 2020

azasypkin mentioned this pull request Oct 16, 2020

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

Merged

azasypkin added the backport pending label Oct 16, 2020

azasypkin mentioned this pull request Oct 16, 2020

[7.10] [Docs] Document Encrypted Saved Objects functionality. (#80183) #80868

Merged

azasypkin added a commit to azasypkin/kibana that referenced this pull request Oct 16, 2020

[Docs] Document Encrypted Saved Objects functionality. (elastic#80183)

e195065

azasypkin added backported and removed backport pending labels Oct 16, 2020


		<1> {kib} will rotate encryption key only for the Saved Objects with the `alert` type in batches of 5000 objects.

		For the time being if you specify decryption-only keys {kib} may try to use them all if it cannot decrypt the Saved Object using the primary encryption key. In most of the cases this overhead is negligible, but if you're constantly dealing with the thousands of the Saved Objects that are encrypted and experiencing performance issues you may want to try to rotate encryption key for those objects.

	You can configure the following settings in the `kibana.yml` file. For more details see <<xpack-security-secure-saved-objects>>.
	These settings control the encryption of saved objects with sensitive data. For more details see <<xpack-security-secure-saved-objects>>.

	\| An arbitrary string of 32 characters or more that is used to encrypt sensitive properties of the Saved Objects before they're stored in {es}. If not set, {kib} will generate a random key on startup, but certain {kib} functionality won't be available until you set the encryption key explicitly.
	\| 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.


		In {kib} you usually deal with dashboards, visualizations, alerts, actions, advanced settings, spaces etc. These are so called Saved Objects that {kib} stores in a dedicated internal {es} index. If such an object includes any sensitive information, for example a PagerDuty’s 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. Moreover, {kib} records any access attempt to such sensitive information in the audit logs.

		Having sensitive information encrypted means that even if a malicious party can somehow get access to the {kib} internal indices, for example through improperly secured backup, they won't be able to extract that information without knowing an encryption key usually stored separately in a keystore or a configuration file. That's why it's critical to use a cryptographically strong encryption key and keep it safe.

	If you don't specify encryption key {kib} will generate a random one automatically at startup time. That means every time you restart {kib} it will use a new ephemeral encryption key and won't be able to decrypt Saved Objects encrypted with another key. To prevent this {kib} plugins may not allow you to perform certain actions until you explicitly set an encryption key.
	If you don't specify encryption key {kib} will generate a random one automatically at startup time. That means every time you restart {kib} it will use a new ephemeral encryption key and won't be able to decrypt Saved Objects encrypted with another key. To prevent data loss, {kib} may disable features which rely on this encryption until you explicitly set an encryption key.


		Many policies and best practices stipulate that encryption keys should be periodically rotated to decrease the amount of content encrypted with one key and hence limit the potential damage in case the key is compromised. {kib} allows you to rotate encryption keys whenever there is a need.

		As a rule of thumb, when you change an encryption key you still keep the old one for some time. While {kib} will only use a new encryption key to encrypt all new and updated data it still may need to know the old one to decrypt data that was encrypted using that old key. Moreover, it's perfectly possible to have multiple old keys used only for decryption. It's worth noting that {kib} doesn't re-encrypt existing Saved Objects with the new encryption key automatically, re-encryption only happens when you update existing object or use bulk key rotation API explained later on.

	<1> Encryption key {kib} will use to encrypt all new or updated Saved Objects, known as a primary encryption key.
	<1> Encryption key {kib} will use to encrypt all new or updated Saved Objects, known as the primary encryption key.

		============================================================================

		At some point you may want to dispose old encryption keys completely, but before that you should make sure there are no Saved Objects left that {kib} encrypted with the encryption key you're going to dispose. You can use bulk key rotation API for that purpose. It will figure out which existing Saved Objects still require decryption-only keys and re-encrypt them with the primary key. It may take a while if you have lots of such Saved Objects:

		@@ -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 encryption key for the saved objects with encrypted attributes

	experimental[] Rotate encryption key for the saved objects with encrypted attributes.
	experimental[] Rotate encryption key for encrypted saved objects.


		experimental[] Rotate encryption key for the saved objects with encrypted attributes.

		For the time being if you specify <<xpack-encryptedSavedObjects-keyRotation-decryptionOnlyKeys, decryption-only keys>> {kib} may try to use them all if it cannot decrypt the saved object using the primary encryption key. In most of the cases this overhead is negligible, but if you're constantly dealing with the thousands of the saved objects that are encrypted and experiencing performance issues you may want to try to rotate encryption key for those objects.

	(number) Indicates the total number of _all_ saved objects with the encrypted attributes, irrespective to the key {kib} used for encryption.
	(number) Indicates the total number of _all_ encrypted saved objects (optionally filtered by the requested `type`), regardless of the key {kib} used for encryption.

	(Optional, string) Limits encryption key rotation only to the saved objects with the specified type. By default, {kib} will try to rotate encryption key for all saved object types that may contain encrypted attributes.
	(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.

	(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 hence splits processing into consequent batches. By default, batch size is 10000 which is also a maximum allowed value.
	(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.

	NOTE: In most of the 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 key for all saved objects with the encrypted attributes.
	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 saved objects with the encrypted attributes.

	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 unknown encryption key.
	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.

	We optimized default parameters for speed and don't expect you to change any of those without a strong need. However, if you're experiencing any issues with this API you may want to decrease a batch size or rotate encryption key for the specific types only. In this case you may need to run key rotation multiple times in a row.
	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 we perform key rotation for all saved objects with the `alert` type in batches of 5000.
	In this example, key rotation is performed for all saved objects with the `alert` type in batches of 5000.

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

	If you don't specify encryption key {kib} will generate a random one automatically at startup time. That means every time you restart {kib} it will use a new ephemeral encryption key and won't be able to decrypt saved objects encrypted with another key. To prevent data loss, {kib} may disable features which rely on this encryption until you explicitly set an encryption key.
	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.

[Docs] Document Encrypted Saved Objects functionality. #80183

[Docs] Document Encrypted Saved Objects functionality. #80183

Conversation

azasypkin commented Oct 12, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elasticmachine commented Oct 13, 2020

legrego left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elasticmachine commented Oct 14, 2020

azasypkin commented Oct 14, 2020

legrego left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gchaps Oct 14, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

azasypkin commented Oct 15, 2020

gchaps left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

legrego left a comment

Choose a reason for hiding this comment

azasypkin commented Oct 16, 2020

azasypkin commented Oct 12, 2020 •

edited

Loading

gchaps Oct 14, 2020 •

edited

Loading

gchaps left a comment •

edited

Loading


		As a rule of thumb, when you change an encryption key you still keep the old one for some time. While {kib} will only use a new encryption key to encrypt all new and updated data it still may need to know the old one to decrypt data that was encrypted using that old key. Moreover, it's perfectly possible to have multiple old keys used only for decryption. It's worth noting that {kib} doesn't re-encrypt existing saved objects with the new encryption key automatically, re-encryption only happens when you update existing object or use <<saved-objects-api-rotate-encryption-key, Rotate encryption key API>>.

		Here is how your `kibana.yml` can look like if you want to use key rotation functionality:

	Here is how your `kibana.yml` can look like if you want to use key rotation functionality:
	Here is how your `kibana.yml` might look if you use key rotation functionality:

	<1> Encryption key {kib} will use to encrypt all new or updated saved objects, known as the primary encryption key.
	<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 only to decrypt existing saved objects if decryption with the primary encryption key isn't possible, known as decryption-only or secondary encryption keys.
	<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.

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

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