--- layout: docs page_title: Data encryption description: >- Learn how key management services protect the encryption keys used for securing data. Understand key lifecycle management best practices. --- ⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️ > [!IMPORTANT] > **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com. ⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️ # Data encryption in Boundary Boundary has multiple mechanisms to ensure secure end-to-end behavior of the system. A key part of this is [support for various Key Management Systems](/boundary/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. ## The `worker-auth-storage` KMS key The `worker-auth-storage` KMS key can be used by [Workers registered using worker-led or controller-led methods](/boundary/docs/workers/registration#authorization-methods) for storage of authentication keys. It is optional for workers; if not specified the authentication keys will not be encrypted on disk. This can not used by workers registered using an external KMS. ## The `root` KMS key and per-scope KEK/DEKs 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 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. You can configure `root` KMS keys for self-managed Enterprise or Community edition deployments. The current scoped DEKs and their purposes are detailed below: - `audit`: This is used to encrypt secret values in the event log. For more information about the event log, refer to [the events config](/boundary/docs/monitor/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. - `tokens`: This is used for encrypting tokens generated by auth methods within the given scope. - `sessions`: This is used as a base key against which to derive session-specific encryption keys. ### Key version lifecycle management You can control the lifecycles of the per-scope KEK and DEKs via the CLI or API using the key endpoints under the scopes section. To rotate all the keys in a scope, use the `rotate-keys` endpoint: ```shell-session $ boundary scopes rotate-keys -scope-id p_A4jfDjZ9jf ``` This endpoint creates new key versions for all keys in the scope `p_A4jfDjZ9jf`, and makes these key versions the active key versions for encrypting new data. The previous key version(s) will continue to be used for decrypting existing data. You can use the `-rewrap` flag to immediately rewrap all DEK versions with the new KEK version. Otherwise, the DEK versions remain encrypted by the prior KEK version from when they were created. To list all keys in a scope and their versions, use the `list-keys` endpoint: ```shell-session $ boundary scopes list-keys -scope-id p_A4jfDjZ9jf ``` To destroy a key version, use the `destroy-key-version` endpoint: ```shell-session $ boundary scopes destroy-key-version -scope-id p_A4jfDjZ9jf -key-version-id kdkv_tr6ZN8opYr ``` The latest key version cannot be destroyed, so if you want to destroy the latest key version, you will need to call the `rotate-keys` endpoint first, to create a new set of key versions. The `oplog` purpose key versions also cannot be destroyed at this time. Destroying a key version sometimes requires background work before it can be completed. This is because DEK versions that currently encrypt data necessitate re-encrypting that data with the latest DEK version for each purpose before they can be deleted. You can monitor the progress of this re-encryption job via the `list-key-destruction-jobs` endpoint: ```shell-session $ boundary scopes list-key-version-destruction-jobs -scope-id p_A4jfDjZ9jf ``` Once the job disappears from this list, the associated key version will have been destroyed and any existing data will have been re-encrypted. ## The `bsr` KMS key This feature requires HCP Boundary or Boundary Enterprise The `bsr` KMS key is required for [session recording](/boundary/docs/session-recording). If you do not add a `bsr` key to your controller configuration, you will receive an error when you attempt to enable session recording. The key is used for encrypting data and checking the integrity of recordings. ## The `previous-root` KMS key The `previous-root` KMS key is used when migrating to a new `root` key. Adding the `previous-root` KMS key to your configuration informs the Controller to use it for decrypting the existing information in the database, allowing you to rotate and rewrap the KEKs to complete the migration to the new root key. You can configure `previous-root` KMS keys for self-managed Enterprise or Community edition deployments. ## The `worker-auth` KMS key The `worker-auth` KMS key is a key shared by the Controller and Worker in order to authenticate a Worker to the Controller. Specifics of this mechanism can be found on the [Connections/TLS page](/boundary/docs/secure/encryption/connections-tls). If a worker is registered with [worker-led or controller-led methods](/boundary/docs/workers/registration#authorization-methods) this is unnecessary. You can configure `worker-auth` KMS keys for HCP, Enterprise, and Community edition deployments. However, you cannot configure `worker-auth` keys for the first set of workers that connect to your HCP workers. ## The `recovery` KMS key The `recovery` KMS key is used for rescue/recovery operations that can be used by a client to authenticate almost any operation within Boundary. Its mechanism of operation is very similar to the `worker-auth` flow in terms of using a shared KMS between the client and the Controller for authentication. A nonce and creation time are included as an encrypted payload, formatted as a token and sent to the Controller. The time and nonce are used to ensure that a value cannot be replayed by an adversary, and also to ensure that each operation must be individually authenticated by a client so that revoking access to the KMS has an immediate result. You can configure `recovery` KMS keys for self-managed Enterprise or Community edition deployments. It is not required for this `kms` configuration block to exist in the Controller's configuration file. It's best practice to leave it out except when actually needed, and to use change control capabilities to ensure that the configuration file modification is authorized. After it's no longer needed, the block should be removed. On the client side, a user can use the `-recovery-config` flag with any operation on the CLI to specify a configuration file containing a suitable `kms` block. This functionality is also accessible via the Go SDK. Requests authorized via this mechanism will show a user of `u_recovery`. This mechanism _cannot_ be used to authorize a session, as there is no uniquely identifying user information available. There are some other situations where this mechanism can be useful. For example, it is possible to use this mechanism, along with some defaults in the Terraform provider, to ensure that _everything_ in Boundary is created through Terraform, with the exception of resources that cannot themselves be deleted. (This consists of built-in anonymous (`u_anon`), authenticated (`u_auth`), and recovery (`u_recovery`) users and the `global` scope.). By initializing Boundary with the options to skip creating default resources, Terraform can be used to create the specific resources needed instead, with the `recovery` KMS used to authenticate setting up the initial auth method(s). ## The `config` KMS key This key can be used to encrypt values within Boundary's configuration file. By sharing this block between Boundary and an operator, the operator can put sensitive or secret values (such as cloud API keys for KMSes) in Boundary's configuration file, run `boundary config encrypt` to encrypt the file, and then safely pass the file to a change control system. Only another operator or system with access to that KMS can decrypt the values. Boundary will check for a `config` KMS block on startup, and if it exists, will use it to decrypt any encrypted values found at startup time. You can configure `config` KMS keys for self-managed Enterprise or Community edition deployments.