From 6f36a1cab6b0c1ea0b064dc80609186da8bdb7b9 Mon Sep 17 00:00:00 2001
From: Jeff Mitchell <jeffrey.mitchell@gmail.com>
Date: Sat, 10 Oct 2020 19:29:34 -0400
Subject: [PATCH] Update security docs (#613)

---
 internal/website/permstable/permstable.go     |  8 +-
 .../security/{tls.mdx => connections-tls.mdx} | 14 +--
 .../concepts/security/data-encryption.mdx     | 99 +++++++++++++++++++
 ...{permissions-model.mdx => permissions.mdx} | 56 +++++------
 .../content/docs/configuration/kms/index.mdx  |  2 +-
 website/data/docs-navigation.js               |  6 +-
 6 files changed, 144 insertions(+), 41 deletions(-)
 rename website/content/docs/concepts/security/{tls.mdx => connections-tls.mdx} (93%)
 create mode 100644 website/content/docs/concepts/security/data-encryption.mdx
 rename website/content/docs/concepts/security/{permissions-model.mdx => permissions.mdx} (97%)

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<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"),
 		},
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.
   </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>
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',