boundary/website/content/docs/concepts/security/data-encryption.mdx

---
layout: docs
page_title: Data Encryption
description: |-
  How Boundary secures data at rest
---

# Data Security 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](/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.

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

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 `root` purpose.

The current scoped DEKs and their purposes are detailed below:

~> Management of these keys is handled entirely internally; the information
provided in this section is purely for informational purposes.

- `database`: This is the general-purpose DEK used to encrypt sensitive or
  secret values within the database.

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

## 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](/docs/concepts/security/connections-tls).

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

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