diff --git a/internal/website/permstable/permstable.go b/internal/website/permstable/permstable.go
index fcc938cb69..d3b896e0eb 100644
--- a/internal/website/permstable/permstable.go
+++ b/internal/website/permstable/permstable.go
@@ -8,7 +8,7 @@ import (
"strings"
)
-const permsFile = "website/content/docs/concepts/permissions.mdx"
+const permsFile = "website/content/docs/concepts/security/permissions.mdx"
var (
iamScopes = []string{"Global", "Org"}
@@ -157,8 +157,8 @@ func (r *Resource) Marshal() (ret []string) {
ret = append(ret, fmt.Sprintf(`%s
`, indent(4)))
if i == 0 {
ret = append(ret,
- fmt.Sprintf(`%s| %s | `, indent(6), len(r.Endpoints), r.Type),
- fmt.Sprintf(`%s`, indent(6), len(r.Endpoints)),
+ fmt.Sprintf(`%s | %s | `, indent(6), len(r.Endpoints), r.Type),
+ fmt.Sprintf(`%s`, indent(6), len(r.Endpoints)),
fmt.Sprintf(`%s`, indent(8)),
)
for _, s := range r.Scopes {
@@ -310,7 +310,7 @@ var account = &Resource{
{
Path: "/accounts",
Params: map[string]string{
- "Type": "accounts",
+ "Type": "account",
},
Actions: clActions("an account"),
},
diff --git a/website/content/docs/concepts/security/tls.mdx b/website/content/docs/concepts/security/connections-tls.mdx
similarity index 93%
rename from website/content/docs/concepts/security/tls.mdx
rename to website/content/docs/concepts/security/connections-tls.mdx
index a0ebaffdf3..fffdb2b64c 100644
--- a/website/content/docs/concepts/security/tls.mdx
+++ b/website/content/docs/concepts/security/connections-tls.mdx
@@ -1,7 +1,7 @@
---
layout: docs
-page_title: TLS
-sidebar_title: TLS
+page_title: Connections/TLS
+sidebar_title: Connections/TLS
description: |-
How Boundary secures its connections
---
@@ -30,11 +30,11 @@ provides broad compatibility with a wide array of clients.
## Worker-to-Controller TLS
The service exposed by the a Controller to handle Worker requests takes
-advantage of the KMS key designated for `worker-auth` within Boundary's
-configuration file, which must point to the same key on the KMS for both the
-Controller and the Worker. Security of the connection relies on secure
-transmission of a single set of allowed TLS parameters, which forms the entire
-allowable CA chain for the connection.
+advantage of the [KMS](/docs/concepts/security/data-encryption) key designated
+for `worker-auth` within Boundary's configuration file, which must point to the
+same key on the KMS for both the Controller and the Worker. Security of the
+connection relies on secure transmission of a single set of allowed TLS
+parameters, which forms the entire allowable CA chain for the connection.
TLS establishment is performed as follows:
diff --git a/website/content/docs/concepts/security/data-encryption.mdx b/website/content/docs/concepts/security/data-encryption.mdx
new file mode 100644
index 0000000000..9c8ab3fbb9
--- /dev/null
+++ b/website/content/docs/concepts/security/data-encryption.mdx
@@ -0,0 +1,99 @@
+---
+layout: docs
+page_title: Data Encryption
+sidebar_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 encrpyting 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; then 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.
+
+~> This mechanism cannot be used to authorize a session, as there is no user information attached to these requests. Requests authorized via this mechanism will show a user of `u_recovery`.
+
+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 (that is, the
+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
+specfici resources needed instead, with the `recovery` KMS used to authenticate
+setting up the initial authentication 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, it will decrypt any encrypted
+values found at startup time.
\ No newline at end of file
diff --git a/website/content/docs/concepts/security/permissions-model.mdx b/website/content/docs/concepts/security/permissions.mdx
similarity index 97%
rename from website/content/docs/concepts/security/permissions-model.mdx
rename to website/content/docs/concepts/security/permissions.mdx
index 4526c87030..1f2abbbdfd 100644
--- a/website/content/docs/concepts/security/permissions-model.mdx
+++ b/website/content/docs/concepts/security/permissions.mdx
@@ -1,12 +1,12 @@
---
layout: docs
-page_title: Permissions Model
-sidebar_title: Permissions Model
+page_title: Permissions
+sidebar_title: Permissions
description: |-
Boundary's permissions model
---
-# Boundary Permissions Model
+# Permissions in Boundary
Boundary's permissions model is a composable, RBAC, allow-only model that
attempts to marry flexibility with usability. This page discusses the permission
@@ -190,8 +190,8 @@ wildcard or templated grant strings.
- | Account |
-
+ | Account |
+
- Global
- Org
@@ -205,7 +205,7 @@ wildcard or templated grant strings.
- Type
@@ -294,8 +294,8 @@ wildcard or templated grant strings.
|
- | Auth Method |
-
+ | Auth Method |
+
- Global
- Org
@@ -381,8 +381,8 @@ wildcard or templated grant strings.
|
- | Auth Token |
-
+ | Auth Token |
+
- Global
- Org
@@ -450,8 +450,8 @@ wildcard or templated grant strings.
|
- | Group |
-
+ | Group |
+
- Global
- Org
@@ -550,8 +550,8 @@ wildcard or templated grant strings.
|
- | Host |
-
+ | Host |
+
@@ -639,8 +639,8 @@ wildcard or templated grant strings.
|
- | Host Catalog |
-
+ | Host Catalog |
+
@@ -719,8 +719,8 @@ wildcard or templated grant strings.
|
- | Host Set |
-
+ | Host Set |
+
@@ -829,8 +829,8 @@ wildcard or templated grant strings.
|
- | Role |
-
+ | Role |
+
- Global
- Org
@@ -947,8 +947,8 @@ wildcard or templated grant strings.
|
- | Scope |
-
+ | Scope |
+
- Global
- Org
@@ -1028,8 +1028,8 @@ wildcard or templated grant strings.
|
- | Session |
-
+ | Session |
+
@@ -1096,8 +1096,8 @@ wildcard or templated grant strings.
|
- | Target |
-
+ | Target |
+
@@ -1200,8 +1200,8 @@ wildcard or templated grant strings.
|
- | User |
-
+ | User |
+
- Global
- Org
diff --git a/website/content/docs/configuration/kms/index.mdx b/website/content/docs/configuration/kms/index.mdx
index 29fbf1096b..20b44a9ed4 100644
--- a/website/content/docs/configuration/kms/index.mdx
+++ b/website/content/docs/configuration/kms/index.mdx
@@ -26,7 +26,7 @@ kms [NAME] {
For example:
```hcl
-kms "pkcs11" {
+kms "transit" {
# ...
}
```
diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js
index 3d39250979..4fc13353ad 100644
--- a/website/data/docs-navigation.js
+++ b/website/data/docs-navigation.js
@@ -35,7 +35,11 @@ export default [
},
{
category: 'security',
- content: ['permissions-model', 'tls'],
+ content: [
+ 'permissions',
+ 'data-encryption',
+ 'connections-tls',
+ ]
},
{
category: 'domain-model',
| |