From 6d25b35b4e7b6109ac63c766cffac6f6b9fd9676 Mon Sep 17 00:00:00 2001 From: Johan Brandhorst-Satzkorn Date: Fri, 18 Nov 2022 13:09:38 -0600 Subject: [PATCH] Add KMS rotation/destruction feature to the changelog and docs (#2600) * Add initial changelog entry * feat(docs): Add initial stab at docs for KMS rotation/destruction * fixup! Add initial changelog entry * Review comments --- CHANGELOG.md | 9 +++++++ .../concepts/security/data-encryption.mdx | 27 ++++++++++--------- 2 files changed, 24 insertions(+), 12 deletions(-) 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.