mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Docs: Database encryption corrections (#57503)
* Docs: Database encryption corrections * Fix relref links * Additional corrections
This commit is contained in:
Joan López de la Franca Beltran
GitHub
parent
2432ce619a
commit
5d18b41857
@ -11,106 +11,78 @@ weight: 700
|
||||
|
||||
# Configure database encryption
|
||||
|
||||
Grafana’s database contains secrets, which are used to query data sources, send alert notifications and perform other functions within Grafana.
|
||||
Grafana’s database contains secrets, which are used to query data sources, send alert notifications, and perform other functions within Grafana.
|
||||
|
||||
Grafana encrypts these secrets before they are written to the database, by using a symmetric-key encryption algorithm called Advanced Encryption Standard (AES), and using a [secret key]({{< relref "../../configure-grafana/#secret_key" >}}) that you can change when you configure a new Grafana instance.
|
||||
Grafana encrypts these secrets before they are written to the database, by using a symmetric-key encryption algorithm called Advanced Encryption Standard (AES). These secrets are signed using a [secret key]({{< relref "../../configure-grafana/#secret_key" >}}) that you can change when you configure a new Grafana instance.
|
||||
|
||||
Since Grafana v9.0, it uses [envelope encryption](#envelope-encryption) by default, which adds a layer of indirection to the
|
||||
encryption process that represents an [**implicit breaking change**](#implicit-breaking-change) for older versions of Grafana.
|
||||
> **Note:** Grafana v9.0 and newer use [envelope encryption](#envelope-encryption) by default, which adds a layer of indirection to the encryption process that introduces an [**implicit breaking change**](#implicit-breaking-change) for older versions of Grafana.
|
||||
|
||||
For further details about how to operate a Grafana instance with envelope encryption, see the [Operational work](#operational-work) section below.
|
||||
For further details about how to operate a Grafana instance with envelope encryption, see the [Operational work]({{< relref "./#operational-work" >}}) section.
|
||||
|
||||
> **Note:** In Grafana Enterprise, you can also choose to [encrypt secrets in AES-GCM mode]({{< relref "#changing-your-encryption-mode-to-aes-gcm" >}}) instead of AES-CFB.
|
||||
> **Note:** In Grafana Enterprise, you can also [encrypt secrets in AES-GCM (Galois/Counter Mode)]({{< relref "#changing-your-encryption-mode-to-aes-gcm" >}}) instead of the default AES-CFB (Cipher FeedBack mode).
|
||||
|
||||
# Envelope encryption
|
||||
## Envelope encryption
|
||||
|
||||
> **Note:** Since Grafana v9.0, you can turn it off by adding the term `disableEnvelopeEncryption` to the list of
|
||||
> feature toggles in your [Grafana configuration]({{< relref "../../configure-grafana/#feature_toggles" >}}).
|
||||
> **Note:** Since Grafana v9.0, you can turn envelope encryption off by adding the feature toggle `disableEnvelopeEncryption` to your [Grafana configuration]({{< relref "../../configure-grafana/#feature_toggles" >}}).
|
||||
|
||||
Instead of encrypting all secrets with a single key, Grafana uses a set of keys called data encryption keys (DEKs) to
|
||||
encrypt them. These data encryption keys are themselves encrypted with a single key encryption key (KEK), configured
|
||||
through the `secret_key` attribute in your
|
||||
[Grafana configuration]({{< relref "../../configure-grafana/#secret_key" >}}) or with a
|
||||
[KMS integration](#encrypting-your-database-with-a-key-from-a-key-management-system-kms).
|
||||
Instead of encrypting all secrets with a single key, Grafana uses a set of keys called data encryption keys (DEKs) to encrypt them. These data encryption keys are themselves encrypted with a single key encryption key (KEK), configured through the `secret_key` attribute in your
|
||||
[Grafana configuration]({{< relref "../../configure-grafana/#secret_key" >}}) or with a [key management service (KMS) integration](#kms-integration).
|
||||
|
||||
## Implicit breaking change
|
||||
### Implicit breaking change
|
||||
|
||||
As stated above, envelope encryption represents an implicit breaking change because it changes the way secrets stored
|
||||
in the Grafana database are encrypted. That means Grafana administrators will be able to transition to Grafana v9.0
|
||||
with no action required from the database encryption perspective, but will need to be extremely careful if they need
|
||||
to roll back to a previous version (e.g. Grafana v8.5) after being updated, because secrets created or modified after upgrade
|
||||
the update to Grafana v9.0 won't be decryptable in previous versions.
|
||||
Envelope encryption introduces an implicit breaking change to versions of Grafana prior to v9.0, because it changes how secrets stored in the Grafana database are encrypted. Grafana administrators can upgrade to Grafana v9.0 with no action required from the database encryption perspective, but must be extremely careful if they need to roll an upgrade back to Grafana v8.5 or earlier because secrets created or modified after upgrading to Grafana v9.0 can’t be decrypted by previous versions.
|
||||
|
||||
Fortunately though, envelope encryption was added in Grafana v8.3 behind a feature toggle. So, in case of emergency,
|
||||
Grafana administrators will be able to downgrade up to Grafana v8.3 and enable envelope encryption as a workaround.
|
||||
Grafana v8.5 implemented envelope encryption behind an optional feature toggle. Grafana administrators who need to downgrade to Grafana v8.5 can enable envelope encryption as a workaround by adding the feature toggle `envelopeEncryption` to the [Grafana configuration]({{< relref "../../configure-grafana/#feature_toggles" >}}).
|
||||
|
||||
> **Note:** In Grafana releases between v8.3 and v8.5, you can turn envelope encryption on by adding the term
|
||||
> `envelopeEncryption` to the list of feature toggles in your
|
||||
> [Grafana configuration]({{< relref "../../configure-grafana/#feature_toggles" >}}).
|
||||
## Operational work
|
||||
|
||||
# Operational work
|
||||
|
||||
From the database encryption perspective, there are several operations that Grafana administrator may want to perform:
|
||||
From the database encryption perspective, Grafana administrators can:
|
||||
|
||||
- [**Re-encrypt secrets**](#re-encrypt-secrets): re-encrypt secrets with envelope encryption and a fresh data key.
|
||||
- [**Roll back secrets**](#roll-back-secrets): decrypt secrets encrypted with envelope encryption and re-encrypt them with legacy encryption.
|
||||
- [**Re-encrypt data keys**](#re-encrypt-data-keys): re-encrypt data keys with a fresh key encryption key and a [KMS integration](#kms-integration).
|
||||
- [**Rotate data keys**](#rotate-data-keys): disable active data keys and stop using them for encryption in favor of a fresh one.
|
||||
|
||||
Find more details about each of those below.
|
||||
### Re-encrypt secrets
|
||||
|
||||
## Re-encrypt secrets
|
||||
You can re-encrypt secrets in order to:
|
||||
|
||||
Secrets re-encryption can be performed when a Grafana administrator wants to either:
|
||||
|
||||
- Move forward already existing secrets' encryption from legacy to envelope encryption.
|
||||
- Move already existing secrets' encryption forward from legacy to envelope encryption.
|
||||
- Re-encrypt secrets after a [data keys rotation](#rotate-data-keys).
|
||||
|
||||
> **Note:** This operation is available through Grafana CLI by running `grafana-cli admin secrets-migration re-encrypt`
|
||||
> command and through Grafana [Admin API]({{< relref "../../../developers/http_api/admin/#re-encrypt-secrets" >}}).
|
||||
> It's safe to run more than once. Recommended to run under maintenance mode.
|
||||
To re-encrypt secrets, use the [Grafana CLI]({{< ref "/cli/" >}}) by running the `grafana-cli admin secrets-migration re-encrypt` command or the `/encryption/reencrypt-secrets` endpoint of the Grafana [Admin API]({{< relref "../../../developers/http_api/admin/#roll-back-secrets" >}}). It's safe to run more than once, more recommended under maintenance mode.
|
||||
|
||||
## Roll back secrets
|
||||
### Roll back secrets
|
||||
|
||||
Used to roll back secrets encrypted with envelope encryption to legacy encryption. It can be used to downgrade to
|
||||
a Grafana version earlier than Grafana v9.0 after an unsuccessful upgrade.
|
||||
You can roll back secrets encrypted with envelope encryption to legacy encryption. This might be necessary to downgrade to Grafana versions prior to v9.0 after an unsuccessful upgrade.
|
||||
|
||||
> **Note:** This operation is available through Grafana CLI by running `grafana-cli admin secrets-migration rollback`
|
||||
> command and through Grafana [Admin API]({{< relref "../../../developers/http_api/admin/#roll-back-secrets" >}}).
|
||||
> It's safe to run more than once. Recommended to run under maintenance mode.
|
||||
To roll back secrets, use the [Grafana CLI]({{< ref "/cli/" >}}) by running the `grafana-cli admin secrets-migration rollback` command or the `/encryption/rollback-secrets` endpoint of the Grafana [Admin API]({{< relref "../../../developers/http_api/admin/#re-encrypt-secrets" >}}). It's safe to run more than once, more recommended under maintenance mode.
|
||||
|
||||
## Re-encrypt data keys
|
||||
### Re-encrypt data keys
|
||||
|
||||
Used to re-encrypt data keys encrypted with a specific key encryption key (KEK). It can be used to either re-encrypt
|
||||
existing data keys with a new key encryption key version (see [KMS integration](#encrypting-your-database-with-a-key-from-a-key-management-system-kms) rotation) or to
|
||||
re-encrypt them with a completely different key encryption key.
|
||||
You can re-encrypt data keys encrypted with a specific key encryption key (KEK). This allows you to either re-encrypt existing data keys with a new KEK version (see [KMS integration](#kms-integration) rotation) or to re-encrypt them with a completely different KEK.
|
||||
|
||||
> **Note:** This operation is available through Grafana CLI by running `grafana-cli admin secrets-migration re-encrypt-data-keys`
|
||||
> command and through Grafana [Admin API]({{< relref "../../../developers/http_api/admin/#re-encrypt-data-encryption-keys" >}}).
|
||||
> It's safe to run more than once. Recommended to run under maintenance mode.
|
||||
To re-encrypt data keys, use the [Grafana CLI]({{< ref "/cli/" >}}) by running the `grafana-cli admin secrets-migration re-encrypt-data-keys` command or the `/encryption/reencrypt-data-keys` endpoint of the Grafana [Admin API]({{< relref "../../../developers/http_api/admin/#re-encrypt-data-encryption-keys" >}}). It's safe to run more than once, more recommended under maintenance mode.
|
||||
|
||||
## Rotate data keys
|
||||
### Rotate data keys
|
||||
|
||||
Data keys rotation can be performed to disable the active data key and therefore stop using them for encryption operations.
|
||||
For high-availability setups, you may need to wait until the data keys cache's TTL (time-to-live) expires to ensure that all
|
||||
rotated data keys are no longer being used for encryption operations.
|
||||
You can rotate data keys to disable the active data key and therefore stop using them for encryption operations. For high-availability setups, you might need to wait until the data keys cache's time-to-live (TTL) expires to ensure that all rotated data keys are no longer being used for encryption operations.
|
||||
|
||||
New data keys for encryption operations are generated on-demand.
|
||||
New data keys for encryption operations are generated on demand.
|
||||
|
||||
> **Note:** It does not imply secrets re-encryption. Therefore, rotated data keys will continue being used to decrypt
|
||||
> those secrets still encrypted with it. Look at [secrets re-encryption](#re-encrypt-secrets) to completely stop using
|
||||
> rotated data keys for both encryption and decryption.
|
||||
> **Note:** Data key rotation does **not** implicitly re-encrypt secrets. Grafana will continue to use rotated data keys to decrypt
|
||||
> secrets still encrypted with them. To completely stop using
|
||||
> rotated data keys for both encryption and decryption, see [secrets re-encryption](#re-encrypt-secrets).
|
||||
|
||||
> **Note:** This operation is available through Grafana [Admin API]({{< relref "../../../developers/http_api/admin/#rotate-data-encryption-keys" >}}).
|
||||
> It's safe to run more than once.
|
||||
To rotate data keys, use the `/encryption/rotate-data-keys` endpoint of the Grafana [Admin API]({{< relref "../../../developers/http_api/admin/#rotate-data-encryption-keys" >}}). It's safe to call more than once, more recommended under maintenance mode.
|
||||
|
||||
## Encrypting your database with a key from a Key Management System (KMS)
|
||||
## Encrypting your database with a key from a key management service (KMS)
|
||||
|
||||
If you are using Grafana Enterprise, you can integrate with a key management system (KMS) provider, and change Grafana’s cryptographic mode of operation from AES-CFB to AES-GCM.
|
||||
If you are using Grafana Enterprise, you can integrate with a key management service (KMS) provider, and change Grafana’s cryptographic mode of operation from AES-CFB to AES-GCM.
|
||||
|
||||
You can choose to encrypt secrets stored in the Grafana database using a key from a KMS, which is a secure central storage location that is designed to help you to create and manage cryptographic keys and control their use across many services. When you integrate with a KMS, Grafana does not directly store your encryption key. Instead, Grafana stores KMS credentials and the identifier of the key, which Grafana uses to encrypt the database.
|
||||
|
||||
Grafana integrates with the following key management systems:
|
||||
Grafana integrates with the following key management services:
|
||||
|
||||
- [AWS KMS]({{< relref "encrypt-secrets-using-aws-kms/" >}})
|
||||
- [Azure Key Vault]({{< relref "encrypt-secrets-using-azure-key-vault/" >}})
|
||||
@ -119,11 +91,6 @@ Grafana integrates with the following key management systems:
|
||||
|
||||
## Changing your encryption mode to AES-GCM
|
||||
|
||||
Grafana encrypts secrets using Advanced Encryption Standard in Cipher
|
||||
FeedBack mode (AES-CFB). You might prefer to use AES in Galois/Counter
|
||||
Mode (AES-GCM) instead, to meet your company’s security requirements or
|
||||
in order to maintain consistency with other services.
|
||||
Grafana encrypts secrets using Advanced Encryption Standard in Cipher FeedBack mode (AES-CFB). You might prefer to use AES in Galois/Counter Mode (AES-GCM) instead, to meet your company’s security requirements or in order to maintain consistency with other services.
|
||||
|
||||
To change your encryption mode, update the `algorithm` value in the
|
||||
`[security.encryption]` section of your Grafana configuration file.
|
||||
For details, refer to [Enterprise configuration]({{< relref "../../configure-grafana/enterprise-configuration/#securityencryption" >}}).
|
||||
To change your encryption mode, update the `algorithm` value in the `[security.encryption]` section of your Grafana configuration file. For further details, refer to [Enterprise configuration]({{< relref "../../configure-grafana/enterprise-configuration/#securityencryption" >}}).
|
||||
|
||||
@ -98,7 +98,7 @@ Grafana Alerting now provides the ability to capture an image for Grafana manage
|
||||
|
||||
## Envelope encryption is generally available and enabled by default
|
||||
|
||||
Grafana now uses envelope encryption to encrypt secrets in the database. Envelope encryption adds a layer of indirection to the encryption process. Instead of encrypting all secrets in the database with a single key, Grafana uses a set of keys called data encryption keys (DEKs) to encrypt them. These data encryption keys are themselves encrypted with a single key encryption key (KEK). This allows you to rotate your KEK and quickly re-encrypt your DEKs in case a key is compromised. In Grafana Enterprise, you can also store your KEK in an external Key Management Service (KMS) like AWS KMS or Azure Key Vault, for extra security. Learn more about envelope encryption in the [docs](https://grafana.com/docs/grafana/next/administration/database-encryption/#envelope-encryption).
|
||||
Grafana now uses envelope encryption to encrypt secrets in the database. Envelope encryption adds a layer of indirection to the encryption process. Instead of encrypting all secrets in the database with a single key, Grafana uses a set of keys called data encryption keys (DEKs) to encrypt them. These data encryption keys are themselves encrypted with a single key encryption key (KEK). This allows you to rotate your KEK and quickly re-encrypt your DEKs in case a key is compromised. In Grafana Enterprise, you can also store your KEK in an external key management service (KMS) like AWS KMS or Azure Key Vault, for extra security. Learn more about envelope encryption in the [database encryption documentation]({{< relref "../setup-grafana/configure-security/configure-database-encryption/#envelope-encryption" >}}).
|
||||
|
||||
{{< figure src="/static/img/docs/enterprise/dashboards/envelope-encryption.png" max-width="750px" caption="Envelope encryption" >}}
|
||||
|
||||
@ -241,23 +241,15 @@ You can find the complete list of breaking changes in the links below. Please ch
|
||||
|
||||
### Envelope encryption enabled by default
|
||||
|
||||
Since v8.3 a new kind of encryption called "envelope encryption" was added, for those secrets stored in the Grafana
|
||||
database (data source credentials, alerting notification channel credentials, oauth tokens, etc), behind a feature
|
||||
toggle named `envelopeEncryption`.
|
||||
Grafana v8.5 added a new kind of encryption called "envelope encryption" for secrets stored in the Grafana database, such as data source credentials, alerting notification channel credentials, oauth tokens, etc., behind a feature toggle named `envelopeEncryption`.
|
||||
|
||||
In v9.0, `envelopeEncryption` feature toggle has been replaced in favor of `disableEnvelopeEncryption` and envelope encryption is
|
||||
the encryption mechanism used by default.
|
||||
In v9.0, the `envelopeEncryption` feature toggle is replaced in favor of `disableEnvelopeEncryption`, and Grafana uses the envelope encryption mechanism by default.
|
||||
|
||||
Therefore, any secret created or updated in Grafana v9.0 won't be decryptable by any previous Grafana version unless the
|
||||
feature toggle `envelopeEncryption` is enabled in the previous version (only available since v8.3).
|
||||
This needs to be considered in high availability setups, progressive rollouts or in case of need to roll back to a previous Grafana version for any reason.
|
||||
Therefore, any secret created or updated in Grafana v9.0 won't be decryptable by any previous Grafana version, unless the Grafana version is at least v8.5 and the feature toggle `envelopeEncryption` is enabled. If not properly configured, this can cause issues in high availability setups, progressive rollouts, or any situation that involves rolling back to a previous Grafana version.
|
||||
|
||||
The recommendation here is to enable `envelopeEncryption` for older versions, or alternatively enable `disableEnvelopeEncryption`
|
||||
before upgrading to v9.0. However, the latter is probably going to be removed in one of the next releases, so we hugely
|
||||
encourage to move on with envelope encryption.
|
||||
We strongly recommend that you enable `envelopeEncryption` for older versions to deploy envelope encryption. You can alternatively configure the `disableEnvelopeEncryption` feature toggle before upgrading to v9.0; however, this feature toggle might be removed in a future Grafana release.
|
||||
|
||||
Find [here]({{< relref "../setup-grafana/configure-security/configure-database-encryption/" >}}) more details and some
|
||||
possible workarounds in case you end up in an undesired situation.
|
||||
For more details, and workarounds for potential issues, refer to the [documentation]({{< relref "../setup-grafana/configure-security/configure-database-encryption/" >}}).
|
||||
|
||||
## A note on Grafana Enterprise licensing
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user