HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Boundary
Boundary Home

You are viewing documentation for version v0.10.x. View latest version.

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

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:

Note: 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 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.

  • 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 OSS Only

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. If a worker is used with PKI authentication this is unnecessary.

The recovery KMS Key OSS Only

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.

Note: 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.

Note: 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 OSS Only

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.