CyberCoveLLC/threshold
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(concepts/auditing/operations): Add description of BSR (#3428)

Browse Source 
Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>
Co-authored-by: Damian Debkowski <Damian.Debkowski@hashicorp.com>
This commit is contained in:
Stan RyzhovDan HeathDamian Debkowski
 authored and GitHub committed 2023-07-18 11:40:52 -07:00
1 parent 1f5d71bf46
commit fb38d059f6
2 files changed
+310 -4
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

website/content/docs/concepts/auditing.mdx
+246 -4
View File
@@ -100,12 +100,254 @@ Boundary creates the top-level directory of the BSR as `<sessionID>.bsr`. This t
A BSR connections directory contains a summary of connections, as well as inbound and outbound requests.
If you use a multiplexed protocol, there are subdirectories for the channels.
```
└── sr_iNCdGSREeX.bsr
├── SHA256SUM
├── SHA256SUM.sig
├── bsrKey.pub
├── cr_3bB78W53Y9.connection
│ ├── SHA256SUM
│ ├── SHA256SUM.sig
│ ├── chr_VUnVuVnITu.channel
│ │ ├── SHA256SUM
│ │ ├── SHA256SUM.sig
│ │ ├── channel-recording-summary.json
│ │ ├── channel-recording.meta
│ │ ├── messages-inbound.data
│ │ ├── messages-outbound.data
│ │ ├── requests-inbound.data
│ │ └── requests-outbound.data
│ ├── chr_nITuVUnVuV.channel
│ │ ├── SHA256SUM
│ │ ├── SHA256SUM.sig
│ │ ├── channel-recording-summary.json
│ │ ├── channel-recording.meta
│ │ ├── messages-inbound.data
│ │ ├── messages-outbound.data
│ │ ├── requests-inbound.data
│ │ └── requests-outbound.data
│ ├── connection-recording-summary.json
│ ├── connection-recording.meta
│ ├── requests-inbound.data
│ └── requests-outbound.data
├── cr_W53Y93bB78.connection
│ ├── SHA256SUM
│ ├── SHA256SUM.sig
│ ├── chr_uVVuUITnVn.channel
│ │ ├── SHA256SUM
│ │ ├── SHA256SUM.sig
│ │ ├── channel-recording-summary.json
│ │ ├── channel-recording.meta
│ │ ├── messages-inbound.data
│ │ ├── messages-outbound.data
│ │ ├── requests-inbound.data
│ │ └── requests-outbound.data
│ ├── connection-recording-summary.json
│ ├── connection-recording.meta
│ ├── requests-inbound.data
│ └── requests-outbound.data
├── pubKeyBsrSignature.sign
├── pubKeySelfSignature.sign
├── session-meta.json
├── session-recording-summary.json
├── session-recording.meta
├── wrappedBsrKey
└── wrappedPrivKey
```
BSR directories are validated based on the contents in the directory.
Each BSR directory contains a SHA256SUMS and SHA256SUMS.sign file that can be used to cryptographically verify the BSR directory's contents.
The SHA256SUMS file contains rows of file names paired with a checksum for the file contents.
The SHA256SUMS.sign is a copy of the SHA256SUMS file, signed with the BSR's private key.
### BSR Session folder
```
└── sr_iNCdGSREeX.bsr
├── SHA256SUM
├── SHA256SUM.sig
├── bsrKey.pub
├── cr_3bB78W53Y9.connection
├── pubKeyBsrSignature.sign
├── pubKeySelfSignature.sign
├── session-meta.json
├── session-recording-summary.json
├── session-recording.meta
├── wrappedBsrKey
└── wrappedPrivKey
```
`session-recording.meta` file example:
```
id: sr_iNCdGSREeX
protocol: BSSH
connection: cr_3bB78W53Y9.connection
```
`session-meta.json` file example:
```
{
"PublicId": "s_HQbVb8fJaM",
"Endpoint": "ssh://openssh-server:2222",
"User": {
"PublicId": "u_5Ry4oDiEVp",
"Scope": {
"PublicId": "global",
"Name": "global",
"Description": "Global Scope",
"Type": "global",
"ParentId": "",
"PrimaryAuthMethodId": "ampw_CdIa5KR9iw"
},
"Name": "admin",
"Description": "Initial admin user within the \"global\" scope"
},
"Target": {
"PublicId": "tssh_TIx4ENZMdA",
"Scope": {
"PublicId": "p_7Qe46uNMYX",
"Name": "session-recording-project",
"Description": "",
"Type": "project",
"ParentId": "o_yK7GoA6OG2",
"PrimaryAuthMethodId": ""
},
"Name": "session-recording-target",
"Description": "",
"DefaultPort": 2222,
"DefaultClientPort": 0,
"SessionMaxSeconds": 28800,
"SessionConnectionLimit": -1,
"WorkerFilter": "",
"EgressWorkerFilter": "",
"IngressWorkerFilter": "\"pki\" in \"/tags/type\"",
"EnableSessionRecording": true,
"StorageBucketId": "sb_vqn871JdQf"
},
"Worker": {
"PublicId": "w_ogOQt0rsuQ",
"Version": "0.13.0",
"Sha": ""
},
"StaticHost": null,
"DynamicHost": null,
"StaticJSONCredentials": null,
"StaticUsernamePasswordCredentials": [
{
"PublicId": "credup_gdzeB5UWJv",
"Name": "",
"Description": "",
"Username": "username",
"PasswordHmac": "PasswordHmac,
"Purposes": [
"injected_application"
],
"CredentialStore": {
"PublicId": "csst_agwIT97uZ7",
"ProjectId": "p_7Qe46uNMYX",
"Name": "ssh static store",
"Description": "SSH Static Cred store"
}
}
],
"StaticSshPrivateKeyCredentials": null,
"VaultGenericLibraries": null,
"VaultSshCertificateLibraries": null
}
```
`session-recording.json` file example:
```
id: sr_iNCdGSREeX
protocol: BSSH
connection: cr_3bB78W53Y9.connection
```
`SHA256SUM` and `SHA256SUM.sig` files are used for cryptographically verifying the contents of this directory.
For more information on `*.sign`, `bsrKey.pub`, `wrappedBsrKey`, and `wrappedPrivKey` files, refer to [Validating the integrity of session recordings](/boundary/docs/operations/manage-recorded-sessions).
### BSR Connection folder
```
└── cr_W53Y93bB78.connection
├── SHA256SUM
├── SHA256SUM.sig
├── chr_uVVuUITnVn.channel
├── connection-recording-summary.json
├── connection-recording.meta
├── requests-inbound.data
└── requests-outbound.data
```
`connection-recording.meta` file example:
```
id: cr_W53Y93bB78
requests: outbound
requests: inbound
channel: chr_uVVuUITnVn.channel
```
`connection-recording-summary.json` file example:
```
{
"Id": "cr_W53Y93bB78",
"ChannelCount": 1,
"StartTime": "2023-07-13T20:21:49.164105381Z",
"EndTime": "2023-07-13T20:22:37.241911112Z",
"BytesUp": 125,
"BytesDown": 748,
"Errors": null
}
```
`*.data` files are binary files containing all data transmitted during a session.
`SHA256SUM` and `SHA256SUM.sig` files are used for cryptographically verifying the contents of this directory.
### BSR Channel folder
```
└── chr_uVVuUITnVn.channel
├── SHA256SUM
├── SHA256SUM.sig
├── channel-recording-summary.json
├── channel-recording.meta
├── messages-inbound.data
├── messages-outbound.data
├── requests-inbound.data
└── requests-outbound.data
```
`channel-recording.meta` file example:
```
id: chr_uVVuUITnVn
channelType: session
messages: outbound
requests: outbound
messages: inbound
requests: inbound
```
`channel-recording-summary.json` file example:
```
{
"ChannelSummary": {
"Id": "chr_uVVuUITnVn",
"ConnectionRecordingId": "cr_W53Y93bB78",
"StartTime": "2023-07-13T20:21:49.230916214Z",
"EndTime": "2023-07-13T20:22:37.229379944Z",
"BytesUp": 125,
"BytesDown": 748,
"ChannelType": "session"
},
"SessionProgram": "shell",
"SubsystemName": "",
"ExecProgram": "",
"FileTransferDirection": "not applicable"
}
```
`*.data` files are binary files containing all data transmitted during a session.
`SHA256SUM` and `SHA256SUM.sig` files are used for cryptographically verifying the contents of this directory.
For more information, refer to the [overview of configuring session recording](/boundary/docs/configuration/session-recording).
website/content/docs/operations/manage-recorded-sessions.mdx
+64
View File
@@ -98,3 +98,67 @@ You can find all recorded sessions in the UI from the global scope.
</Tab>
</Tabs>
## Validate the integrity of session recordings
BSR directories are validated based on the contents in the directory.
Boundary cryptographically verifies each individual Boundary Session Recording (BSR) file. The keys used for verifying all
Boundary Session Recording files are written to storage and wrapped by the KMS you configured. Each session recording
has its own individual key. Boundary generates the following keys when a session recording is authorized:
- The BSR key is a plaintext AES-GCM key. It is not uploaded to the external object store.
- The private and public key pair is a ed25519 key pair. The key pair is not uploaded to the external object store.
The following files are stored in the BSR file structure to ensure the integrity of a session recording:
- `bsrKey.pub` is the public ed25519 key.
- `wrappedBsrKey` is the BSR key wrapped by the external KMS AES-GCM key that you configure.
- `wrappedPrivKey` is the private ed25519 key wrapped by the external KMS AES-GCM key that you configure.
- `pubKeySelfSignature.sign` is a self-signature of the plaintext public ed25519 key created with its private key.
- `pubKeyBsrSignature.sign` is a signature of the plaintext public ed25519 key created with the BSR key.
- `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
Encrypting the BSR key with an external KMS means that Boundary is not responsible for the longevity of the keys.
The Boundary admin can always use that external KMS to unwrap the `wrappedBsrKey` and `wrappedPrivKey`.
A BSR’s key is encrypted using the `go-kms-wrapping` package, and therefore the encrypted BlobInfo includes the metadata required to identify the key-version used during encryption.
So if the wrapper is reinitialized properly, you can unwrap the keys even if the key has been rotated.
Each BSR directory contains a SHA256SUM and SHA256SUM.sig file that you can use to cryptographically verify the BSR directory's contents.
The SHA256SUM file contains rows of file names paired with a checksum for the file contents.
The SHA256SUM.sig is a copy of the SHA256SUM file, signed with the BSR's private key.
Refer to the following example of a SHA256SUM file:
```
dc8ce2c42553ce510197c99efe21d89d6229feb4b49170511f49965f2e3cf1a3 wrappedBsrKey
a5a91b1b52fb53c4bab661b2e5846bb2a836f050e3d745e436078871914a0bc2 wrappedPrivKey
1ca281852ec0d447b94708f28a51b562d47b84affdba25e13a97b0fbd9126424 pubKeyBsrSignature.sign
7b5e18e5930bb4cce12a3f203328d9065cae29f26aba3963bb5faece2cf97231 pubKeySelfSignature.sign
dc7c6b1316624c7c486a22bab157f947df92b9f2ce4a72469b1f335399a043d5 bsrKey.pub
4d3966c458f4e5d67f9ac70b804540b927c718965267c3f36526bf0b18c40ad9 session-meta.json
6fec2173d331828677fb5e77fc19168daad3c5f0e82517a82e5701e6c2bdcbe1 session-recording.meta
ad76483e7cf3e65391a3a1d0b86a3ad436333ee225bea042b13900abc188b226 session-recording-summary.json
```
Follow these steps to validate a session recording:
1. Unwrap `wrappedBsrKey` using the external KMS you configured to retrieve the BSR key.
2. Unwrap `wrappedPrivKey` using the external KMS you configured to retrieve the private key.
3. Use the BSR key or the private key to verify the `bsrKey.pub` key using `go-kms-wrapping` HmacSha256(...)
4. When the key is verified, use the `bsrKey.pub` key to verify the BSR SHA256SUM file using `go-kms-wrapping` ed25519.Sign(...)
## Validate the data integrity in the external object store
When a Boundary worker uploads a BSR file to AWS S3 through the Boundary AWS plugin, the plugin calculates the SHA256 checksum of the
contents of the BSR file and attaches this information to the object that is uploaded to S3. The SHA256 checksum value attached to the
S3 object is returned to the Boundary worker. The Boundary worker calculates the SHA256 checksum value of the BSR file's content from
local disk and compares it to the plugin value. This process ensures that no tampering of BSR files occurs between the worker, plugin, and S3.
The SHA256 checksum value generated by the plugin is not a part of the BSR file structure and should not be confused with how Boundary
cryptographically verifies the BSR directory's contents.
For more information, refer to the [overview of configuring session recording](/boundary/docs/configuration/session-recording).