diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7792c3cfd..470c60bf6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -32,6 +32,15 @@ Canonical reference for changes, improvements, and bugfixes for Boundary.
string after a specified substring; this is useful for pulling an user/account name from an email address. In the following example it uses the account email can be any other parameter:
* `{{ truncateFrom .Account.Email "@" }}`: this would turn `foo@example.com` into `foo`
+* Per-scope key lifecycle management: You can now manage the lifecycles of both Key
+ Encryption Keys (KEKs) and Data Encryption Keys (DEKs) using the new key rotation
+ and key version destruction functionality. To learn more about this new feature,
+ refer to the
+ [documentation](https://developer.hashicorp.com/boundary/docs/concepts/security/data-encryption).
+
+ Upgrade notice: If the Database purpose DEK for a scope is destroyed, you must use
+ the API to cancel any sessions that predate the upgrade.
+ ([PR](https://github.com/hashicorp/boundary/pull/2477))
* Custom Response Headers: Adds ability to set api and ui response headers based
on status code. Includes default secure CSP and other headers.
diff --git a/website/content/docs/concepts/security/data-encryption.mdx b/website/content/docs/concepts/security/data-encryption.mdx
index 61f1219f4..ca395970c 100644
--- a/website/content/docs/concepts/security/data-encryption.mdx
+++ b/website/content/docs/concepts/security/data-encryption.mdx
@@ -13,11 +13,6 @@ Systems](/docs/configuration/kms) that protect the base encryption keys used
for various functions. This page describes the various KMS key purposes that
Boundary supports and how they are used within the system.
-~> **Note:** Boundary does not currently support rotation of its internal keys, but this
-will be supported in a future version. External keys can be rotated so long as
-the original keys remain available for decryption; full support for rotating
-these will come in a future version as well.
-
## The `worker-auth-storage` KMS Key
The `worker-auth-storage` KMS key is used by a [PKI
@@ -25,27 +20,35 @@ Worker](/docs/configuration/worker/pki-worker) for storage of authentication
keys. It is optional for PKI workers; if not specified the authentication keys
will not be encrypted on disk. This is not used by KMS workers.
-## The `root` KMS Key and Per-Scope KEK/DEKs OSS Only
+## The `rootKey` KMS Key and Per-Scope KEK/DEKs OSS Only
Following best practices of using different encryption keys for different
purposes, Boundary has a number of encryption keys generated within each scope.
+Each key further contains versions, which hold the key material used to encrypt
+data. You can create new key versions by _rotating_ the keys. A key version
+can be destroyed, which will re-encrypt any existing data before destroying the
+key material permanently.
-The `root` KMS key acts as a KEK (Key Encrypting Key) for the scope-specific
-KEKs (also referred to as the scope's `root` key). The scope's `root` KEK
+The `rootKey` KMS key acts as a KEK (Key Encrypting Key) for the scope-specific
+KEKs (also referred to as the scope's `rootKey` key). The scope's `rootKey` KEK
and the various DEKs (Data Encryption Keys) are created when a scope is created.
-The DEKs are encrypted with the scope's `root` KEK, and this is in turn
-encrypted with the KMS key marked for the `root` purpose.
+The DEKs are encrypted with the scope's `rootKey` KEK, and this is in turn
+encrypted with the KMS key marked for the `rootKey` purpose.
The current scoped DEKs and their purposes are detailed below:
-~> **Note:** Management of these keys is handled entirely internally; the information
-provided in this section is purely for informational purposes.
+- `audit`: This is used to encrypt secret values in the event log. For more
+ information about the event log, refer to
+ [the events config](/docs/configuration/events).
- `database`: This is the general-purpose DEK used to encrypt values within the
database. Values that are encrypted are those generally considered to be
secret, such as API keys, third-party tokens, certificate private keys, and so
on.
+- `oidc`: This is used to encrypt OIDC information in cookies and authentication
+ requests.
+
- `oplog`: This is used for encrypting oplog (operation log) values for the
given scope.