aherman
/
boundary
mirror of https://github.com/hashicorp/boundary
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs(bsr): explain BSR files in detail (#4546)

Browse Source 
* docs(bsr): explain BSR files in detail
carlos
Irena Rindos 2 years ago committed by GitHub
parent af9db26b52
commit 46a16b91e5
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 82 additions and 83 deletions
Show Stats Download Patch File Download Diff File

159
website/content/docs/concepts/auditing.mdx
Unescape View File

@ -101,19 +101,40 @@ Any session recording metadata that is attached to the storage bucket is deleted
The BSR (Boundary Session Recording) defines a hierarchical directory structure of files and a binary file format. The BSR (Boundary Session Recording) defines a hierarchical directory structure of files and a binary file format.
It contains all the data transmitted between a user and a target during a single session. It contains all the data transmitted between a user and a target during a single session.
Boundary creates the top-level directory of the BSR as `<sessionID>.bsr`. This top level directory contains session summary information and subdirectories for connections. Boundary creates the top-level directory of the BSR as `<sessionRecordingID>.bsr`. This top level directory contains session summary
information and subdirectories for connections.
A BSR connections directory contains a summary of connections, as well as inbound and outbound requests. 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. If you use a multiplexed protocol, there are subdirectories for the channels.
Every directory contains a SHA256SUMS and SHA256SUMS.sig file, to be used for cryptographically verifying the contents of
that directory. The SHA256SUMS file contains rows of file names paired with a checksum for file contents. The
SHA256SUMS.sign is a copy of the SHA256SUMS file, signed with the BSR’s private key. For more information on verifying a
session recording, refer to [Validating the integrity of session recordings](/boundary/docs/operations/session-recordings/validate-session-recordings).
The example BSR below is for a multiplexed session recording with the ID `sr_iNCdGSREeX`. The session recording contains one connection,
`cr_3bB78W53Y9`. Connection `cr_3bB78W53Y9` contains two channels, `chr_VUnVuVnITu` and `chr_nITuVUnVuV`.
The files in each directory are explained in the following sections.
``` ```
└── sr_iNCdGSREeX.bsr └── sr_iNCdGSREeX.bsr
├── SHA256SUM ├── SHA256SUM
├── SHA256SUM.sig ├── SHA256SUM.sig
├── bsrKey.pub ├── bsrKey.pub
├── pubKeyBsrSignature.sign
├── pubKeySelfSignature.sign
├── session-meta.json
├── session-recording-summary.json
├── session-recording.meta
├── wrappedBsrKey
├── wrappedPrivKey
├── cr_3bB78W53Y9.connection ├── cr_3bB78W53Y9.connection
│ ├── SHA256SUM │ ├── SHA256SUM
│ ├── SHA256SUM.sig │ ├── SHA256SUM.sig
│ ├── connection-recording-summary.json
│ ├── connection-recording.meta
│ ├── requests-inbound.data
│ ├── requests-outbound.data
│ ├── chr_VUnVuVnITu.channel │ ├── chr_VUnVuVnITu.channel
│ │ ├── SHA256SUM │ │ ├── SHA256SUM
│ │ ├── SHA256SUM.sig │ │ ├── SHA256SUM.sig
@ -132,50 +153,29 @@ If you use a multiplexed protocol, there are subdirectories for the channels.
│ │ ├── messages-outbound.data │ │ ├── messages-outbound.data
│ │ ├── requests-inbound.data │ │ ├── requests-inbound.data
│ │ └── requests-outbound.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 Session folder ### BSR Session folder
``` A BSR session folder contains the following files:
└── sr_iNCdGSREeX.bsr - `SHA256SUM.sig` is a plaintext file that contains rows of file names paired with a checksum for file contents.
├── SHA256SUM - `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
├── SHA256SUM.sig - `bsrKey.pub` is the public ed25519 key.
├── bsrKey.pub - `pubKeySelfSignature.sign` is a self-signature of the plaintext public ed25519 key created with its private key.
├── cr_3bB78W53Y9.connection - `pubKeyBsrSignature.sign` is a signature of the plaintext public ed25519 key created with the BSR key.
├── pubKeyBsrSignature.sign - `wrappedBsrKey` is the BSR key wrapped by the external KMS AES-GCM key that you configure.
├── pubKeySelfSignature.sign - `wrappedPrivKey` is the private ed25519 key wrapped by the external KMS AES-GCM key that you configure.
├── session-meta.json - `session-meta.json` is a JSON file that contains metadata about the session, including the session id, endpoint,
├── session-recording-summary.json user, target, host, worker, and credentials used to access the target. The intention of this file is to provide all information
├── session-recording.meta relevant to the recorded session so that the BSR provides a complete snapshot of a session even in the absence of the Boundary
├── wrappedBsrKey control plane.
└── wrappedPrivKey - `session-recording.meta` is a plaintext file that contains metadata about the session, including the session id, protocol,
``` and a connection ids. For each connection id listed, there should be a corresponding connection directory in the session directory.
- `session-recording-summary.json` is a JSON file that contains a summary of the session recording, including the session id, connection count,
start time, end time, and any errors encountered during recording of the session.
`session-recording.meta` file example: `session-recording.meta` file example:
@ -185,6 +185,19 @@ protocol: BSSH
connection: cr_3bB78W53Y9.connection connection: cr_3bB78W53Y9.connection
``` ```
`session-recording-summary.json` file example:
```
{
"Id": "sr_iNCdGSREeX",
"ConnectionCount": 1,
"StartTime": "2023-09-19T15:05:39.343307163Z",
"EndTime": "2023-09-19T15:08:02.953159598Z",
"Errors": ""
}
```
`session-meta.json` file example: `session-meta.json` file example:
``` ```
@ -258,29 +271,16 @@ connection: cr_3bB78W53Y9.connection
} }
``` ```
`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/session-recordings/validate-session-recordings).
### BSR Connection folder ### BSR Connection folder
A BSR connection folder contains the following files:
``` - `SHA256SUM.sig` is a plaintext file that contains rows of file names paired with a checksum for file contents.
└── cr_W53Y93bB78.connection - `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
├── SHA256SUM - `connection-recording.meta` is a plaintext file that contains metadata about the connection, including the connection id,
├── SHA256SUM.sig requests seen, channel ids, and any errors seen. For each channel id listed, there should be a corresponding channel directory in the connection directory.
├── chr_uVVuUITnVn.channel - `connection-recording-summary.json` is a JSON file that contains a summary of the connection, including the connection id,
├── connection-recording-summary.json start time, end time, bytes up, bytes down, and any errors encountered during recording the connection.
├── connection-recording.meta - `requests-inbound.data` is a binary file containing all inbound SSH request messages transmitted for the connection.
├── requests-inbound.data - `requests-outbound.data` is a binary file containing all outbound SSH request messages transmitted for the connection.
└── requests-outbound.data
```
`connection-recording.meta` file example: `connection-recording.meta` file example:
@ -289,6 +289,7 @@ id: cr_W53Y93bB78
requests: outbound requests: outbound
requests: inbound requests: inbound
channel: chr_uVVuUITnVn.channel channel: chr_uVVuUITnVn.channel
error: error message would be appear here
``` ```
`connection-recording-summary.json` file example: `connection-recording-summary.json` file example:
@ -305,22 +306,19 @@ channel: chr_uVVuUITnVn.channel
} }
``` ```
`*.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 ### BSR Channel folder
A BSR connection folder contains the following files:
``` - `SHA256SUM.sig` is a plaintext file that contains rows of file names paired with a checksum for file contents.
└── chr_uVVuUITnVn.channel - `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
├── SHA256SUM - `channel-recording.meta` is a plaintext file that contains metadata about the channel, including the channel id,
├── SHA256SUM.sig inbound and outbound requests seen, and inbound and outbound messages seen.
├── channel-recording-summary.json - `channel-recording-summary.json` is a JSON file that contains a summary of the channel, including the channel id,
├── channel-recording.meta start time, end time, bytes up, bytes down, channel type, session program, subsystem name (if applicable), exec program (if applicable),
├── messages-inbound.data and file transfer direction (if applicable).
├── messages-outbound.data - `requests-inbound.data` is a binary file containing all inbound SSH request messages transmitted for the channel.
├── requests-inbound.data - `requests-outbound.data` is a binary file containing all outbound SSH request messages transmitted for the channel.
└── requests-outbound.data - `messages-inbound.data` is a binary file containing all inbound SSH data transmitted for the channel.
``` - `messages-outbound.data` is a binary file containing all outbound SSH data transmitted for the channel.
`channel-recording.meta` file example: `channel-recording.meta` file example:
@ -353,7 +351,4 @@ requests: inbound
} }
``` ```
`*.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). For more information, refer to the [overview of configuring session recording](/boundary/docs/configuration/session-recording).

6
website/content/docs/operations/session-recordings/validate-session-recordings.mdx
Unescape View File

@ -56,4 +56,8 @@ Follow these steps to validate a session recording:
1. Unwrap `wrappedBsrKey` using the external KMS you configured to retrieve the BSR key. 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. 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(...). 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(...). 4. When the key is verified, use the `bsrKey.pub` key to verify the BSR SHA256SUM.sig file using `go-kms-wrapping` ed25519.Sign(...).
5. After verifying the SHA256SUM.sig file, use the `sha256` commandline tool to verify BSR checksums using `sha256sum -c SHA256SUM`.
6. Examine the *.meta files in the directory. For session-recording.meta, every connection logged in the meta file should
correspond to a connection folder in the directory. For a connection-recording.meta, every channel logged in the meta file should
correspond to a channel folder in the directory.

Write Preview
Loading…
Cancel
Save