From 9d3f3da4df5bd8d65f9a720ac4a89a2138af37cf Mon Sep 17 00:00:00 2001
From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>
Date: Thu, 9 May 2024 12:32:51 -0400
Subject: [PATCH] docs: Add bsr purpose key examples (#4785)

* docs: Add bsr purpose key examples

* Apply batch of suggestions from code review

Co-authored-by: Michael Li <michael.li@hashicorp.com>

---------

Co-authored-by: Michael Li <michael.li@hashicorp.com>
---
 .../content/docs/configuration/controller.mdx | 28 +++++++++++++++++--
 .../configure-controllers.mdx                 | 16 +++++++++--
 2 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/website/content/docs/configuration/controller.mdx b/website/content/docs/configuration/controller.mdx
index 85f1f11cdf..e243bbda03 100644
--- a/website/content/docs/configuration/controller.mdx
+++ b/website/content/docs/configuration/controller.mdx
@@ -193,9 +193,23 @@ And optionally, a KMS stanza for configuration encryption purpose:
 # Configuration encryption block: decrypts sensitive values in the
 # configuration file. See `boundary config [encrypt|decrypt] -h`.
 kms "aead" {
-  purpose   = "config"`
+  purpose = "config"
   aead_type = "aes-gcm"
-  key       = "7xtkEoS5EXPbgynwd+dDLHopaCqK8cq0Rpep4eooaTs="
+  key = "7xtkEoS5EXPbgynwd+dDLHopaCqK8cq0Rpep4eooaTs="
+}
+```
+
+And optionally, a KMS stanza to enable the session recording feature:
+
+```hcl
+# BSR encryption block: encrypts data and checks the integrity
+# of session recordings. If you do not add a BSR key to your
+# controller configuration, you cannot enable session recording.
+kms "aead" {
+  purpose = "bsr"
+  aead_type = "aes-gcm"
+  key = "8Vg!XCbS.fzNKB@Uu.ccB588H#4iyHAd:TpgjuwC/;J;"
+  key_id = "session_recording"
 }
 ```
 
@@ -315,4 +329,14 @@ kms "aead" {
   key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
   key_id = "global_recovery"
 }
+
+# BSR encryption block: encrypts data and checks the integrity
+# of session recordings. If you do not add a BSR key to your
+# controller configuration, you cannot enable session recording.
+kms "aead" {
+  purpose = "bsr"
+  aead_type = "aes-gcm"
+  key = "8Vg!XCbS.fzNKB@Uu.ccB588H#4iyHAd:TpgjuwC/;J;"
+  key_id = "session_recording"
+}
 ```
diff --git a/website/content/docs/install-boundary/configure-controllers.mdx b/website/content/docs/install-boundary/configure-controllers.mdx
index 65814ae543..a6aef8785e 100644
--- a/website/content/docs/install-boundary/configure-controllers.mdx
+++ b/website/content/docs/install-boundary/configure-controllers.mdx
@@ -38,10 +38,13 @@ The DEKs are encrypted with the scope's root KEK, and this is in turn encrypted
 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.
 
-The following key is optional:
+The following keys are optional:
 
 - **Worker-auth key (Optional)**: The worker-auth KMS key is shared by the controller and worker to authenticate a worker to the controller.
 If a worker is used with PKI authentication, this is unnecessary.
+- **BSR key (Optional)**: The BSR KMS key is required for session recording.
+Boundary uses the BSR key for encrypting data and checking the integrity of recordings.
+If you do not add a BSR key to your controller configuration, you receive an error when you attempt to enable session recording.
 
 There are other optional KMS keys that you can configure for different encryption scenarios.
 These scenarios include Boundary worker PKI auth encryption and Boundary worker or controller configuration encryption.
@@ -237,7 +240,7 @@ kms "awskms" {
   endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
 }
 
-# Worker-Auth KMS Key (optional, only needed if using
+# Worker-Auth KMS Key (optional, only needed if you use
 # KMS authenticated workers)
 kms "awskms" {
   purpose    = "worker-auth"
@@ -245,6 +248,15 @@ kms "awskms" {
   kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey3"
   endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
 }
+
+# BSR KMS Key (optional, only needed if you use the
+# session recording feature)
+kms "awskms" {
+  purpose    = "bsr"
+  region     = "us-east-1"
+  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey4"
+  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
+}
 ```
 </CodeBlockConfig>