Update security docs (#613)
This commit is contained in:
Jeff Mitchell authored and 
GitHub committed
1 parent
b340a0f9ee
commit
6f36a1cab6
6 files changed
+144
-41
No files matched your search
@@ -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<tr>`, indent(4)))
|
||||
if i == 0 {
|
||||
ret = append(ret,
|
||||
fmt.Sprintf(`%s<td rowspan="%d">%s</td>`, indent(6), len(r.Endpoints), r.Type),
|
||||
fmt.Sprintf(`%s<td rowspan="%d">`, indent(6), len(r.Endpoints)),
|
||||
fmt.Sprintf(`%s<td rowSpan="%d">%s</td>`, indent(6), len(r.Endpoints), r.Type),
|
||||
fmt.Sprintf(`%s<td rowSpan="%d">`, indent(6), len(r.Endpoints)),
|
||||
fmt.Sprintf(`%s<ul>`, 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"),
|
||||
},
|
||||
|
||||
+7
-7
@@ -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:
|
||||
|
||||
@@ -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.
|
||||
+28
-28
@@ -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.
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td rowspan="2">Account</td>
|
||||
<td rowspan="2">
|
||||
<td rowSpan="2">Account</td>
|
||||
<td rowSpan="2">
|
||||
<ul>
|
||||
<li>Global</li>
|
||||
<li>Org</li>
|
||||
@@ -205,7 +205,7 @@ wildcard or templated grant strings.
|
||||
<li>Type</li>
|
||||
<ul>
|
||||
<li>
|
||||
<code>accounts</code>
|
||||
<code>account</code>
|
||||
</li>
|
||||
</ul>
|
||||
</ul>
|
||||
@@ -294,8 +294,8 @@ wildcard or templated grant strings.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2">Auth Method</td>
|
||||
<td rowspan="2">
|
||||
<td rowSpan="2">Auth Method</td>
|
||||
<td rowSpan="2">
|
||||
<ul>
|
||||
<li>Global</li>
|
||||
<li>Org</li>
|
||||
@@ -381,8 +381,8 @@ wildcard or templated grant strings.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2">Auth Token</td>
|
||||
<td rowspan="2">
|
||||
<td rowSpan="2">Auth Token</td>
|
||||
<td rowSpan="2">
|
||||
<ul>
|
||||
<li>Global</li>
|
||||
<li>Org</li>
|
||||
@@ -450,8 +450,8 @@ wildcard or templated grant strings.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2">Group</td>
|
||||
<td rowspan="2">
|
||||
<td rowSpan="2">Group</td>
|
||||
<td rowSpan="2">
|
||||
<ul>
|
||||
<li>Global</li>
|
||||
<li>Org</li>
|
||||
@@ -550,8 +550,8 @@ wildcard or templated grant strings.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2">Host</td>
|
||||
<td rowspan="2">
|
||||
<td rowSpan="2">Host</td>
|
||||
<td rowSpan="2">
|
||||
<ul>
|
||||
<li>Project</li>
|
||||
</ul>
|
||||
@@ -639,8 +639,8 @@ wildcard or templated grant strings.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2">Host Catalog</td>
|
||||
<td rowspan="2">
|
||||
<td rowSpan="2">Host Catalog</td>
|
||||
<td rowSpan="2">
|
||||
<ul>
|
||||
<li>Project</li>
|
||||
</ul>
|
||||
@@ -719,8 +719,8 @@ wildcard or templated grant strings.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2">Host Set</td>
|
||||
<td rowspan="2">
|
||||
<td rowSpan="2">Host Set</td>
|
||||
<td rowSpan="2">
|
||||
<ul>
|
||||
<li>Project</li>
|
||||
</ul>
|
||||
@@ -829,8 +829,8 @@ wildcard or templated grant strings.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2">Role</td>
|
||||
<td rowspan="2">
|
||||
<td rowSpan="2">Role</td>
|
||||
<td rowSpan="2">
|
||||
<ul>
|
||||
<li>Global</li>
|
||||
<li>Org</li>
|
||||
@@ -947,8 +947,8 @@ wildcard or templated grant strings.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2">Scope</td>
|
||||
<td rowspan="2">
|
||||
<td rowSpan="2">Scope</td>
|
||||
<td rowSpan="2">
|
||||
<ul>
|
||||
<li>Global</li>
|
||||
<li>Org</li>
|
||||
@@ -1028,8 +1028,8 @@ wildcard or templated grant strings.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2">Session</td>
|
||||
<td rowspan="2">
|
||||
<td rowSpan="2">Session</td>
|
||||
<td rowSpan="2">
|
||||
<ul>
|
||||
<li>Project</li>
|
||||
</ul>
|
||||
@@ -1096,8 +1096,8 @@ wildcard or templated grant strings.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2">Target</td>
|
||||
<td rowspan="2">
|
||||
<td rowSpan="2">Target</td>
|
||||
<td rowSpan="2">
|
||||
<ul>
|
||||
<li>Project</li>
|
||||
</ul>
|
||||
@@ -1200,8 +1200,8 @@ wildcard or templated grant strings.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2">User</td>
|
||||
<td rowspan="2">
|
||||
<td rowSpan="2">User</td>
|
||||
<td rowSpan="2">
|
||||
<ul>
|
||||
<li>Global</li>
|
||||
<li>Org</li>
|
||||
@@ -26,7 +26,7 @@ kms [NAME] {
|
||||
For example:
|
||||
|
||||
```hcl
|
||||
kms "pkcs11" {
|
||||
kms "transit" {
|
||||
# ...
|
||||
}
|
||||
```
|
||||
@@ -35,7 +35,11 @@ export default [
|
||||
},
|
||||
{
|
||||
category: 'security',
|
||||
content: ['permissions-model', 'tls'],
|
||||
content: [
|
||||
'permissions',
|
||||
'data-encryption',
|
||||
'connections-tls',
|
||||
]
|
||||
},
|
||||
{
|
||||
category: 'domain-model',
|
||||
|
||||
Reference in new issue
Block a user