docs: IA reorganization (#5838)
* docs: IA reorganization * docs: Updates * docs: Updates * docs: Fix links * docs: Updates * docs: Fix a typo * docs: Fix client agent topic * docs: Update Client Agent nav * docs: Fix conflict * docs: Fix a typo in Client Agent docs (#5853) * docs: Fix client agent topic * docs: Updates * docs: Updates * docs: Updates * docs: Updates * docs: Fixes get started and operations links * docs: Update nav * docs: Partials * docs: Unix partials * docs: Worker partials * docs: Updates * docs: Update workers and targets * docs: Updates * docs: Updates * docs: Fixes link * docs: Updates after sync review * docs: Updates from review feedback * docs: Move worker filter examples * docs: Fix links * docs: Updates for filters based on working session * docs: Fixes broken links * docs: Add links to other filter topics * docs: Update list intro * docs: Adds link * docs: Fixes redirects * docs: Fixes redirects * docs: Deleted mysql page from TOC * docs: Add versioned redirect * docs: Adds versioned redirects * docs: Adds versioned redirects * docs: Update redirects * docs: Update redirects * docs: Redirect fixes * docs: Update redirect format * docs: Fix a typo * docs: Fixes redirects * docs: Fixes redirect * docs: Adds links out to client agent troubleshooting * uses /etc/boundary.d/ as recommended installation directory (#6003) * docs: Updates legacy io links * docs: Fixes redirects * docs: Fix redirect * docs: Restoring deleted file --------- Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>
This commit is contained in:
Dan HeathandRobin Beck authored and 
GitHub committed
1 parent
21fce7c5eb
commit
5ce6515156
253 files changed
+7897
-5673
No files matched your search
@@ -0,0 +1,191 @@
|
||||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
|
||||
|
||||
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.
|
||||
|
||||
<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.
|
||||
|
||||
</Note>
|
||||
|
||||
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.
|
||||
Reference in new issue
Block a user