docs(bsr): explain BSR files in detail (#4546)
* docs(bsr): explain BSR files in detail
This commit is contained in:
Irena Rindos authored and 
GitHub committed
1 parent
af9db26b52
commit
46a16b91e5
2 files changed
+82
-83
No files matched your search
@@ -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.
|
||||
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.
|
||||
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
|
||||
├── SHA256SUM
|
||||
├── SHA256SUM.sig
|
||||
├── bsrKey.pub
|
||||
├── pubKeyBsrSignature.sign
|
||||
├── pubKeySelfSignature.sign
|
||||
├── session-meta.json
|
||||
├── session-recording-summary.json
|
||||
├── session-recording.meta
|
||||
├── wrappedBsrKey
|
||||
├── wrappedPrivKey
|
||||
├── cr_3bB78W53Y9.connection
|
||||
│ ├── SHA256SUM
|
||||
│ ├── SHA256SUM.sig
|
||||
│ ├── connection-recording-summary.json
|
||||
│ ├── connection-recording.meta
|
||||
│ ├── requests-inbound.data
|
||||
│ ├── requests-outbound.data
|
||||
│ ├── chr_VUnVuVnITu.channel
|
||||
│ │ ├── SHA256SUM
|
||||
│ │ ├── SHA256SUM.sig
|
||||
@@ -132,50 +153,29 @@ If you use a multiplexed protocol, there are subdirectories for the channels.
|
||||
│ │ ├── 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 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
|
||||
```
|
||||
A BSR session folder contains the following files:
|
||||
- `SHA256SUM.sig` is a plaintext file that contains rows of file names paired with a checksum for file contents.
|
||||
- `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
|
||||
- `bsrKey.pub` is the public ed25519 key.
|
||||
- `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.
|
||||
- `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.
|
||||
- `session-meta.json` is a JSON file that contains metadata about the session, including the session id, endpoint,
|
||||
user, target, host, worker, and credentials used to access the target. The intention of this file is to provide all information
|
||||
relevant to the recorded session so that the BSR provides a complete snapshot of a session even in the absence of the Boundary
|
||||
control plane.
|
||||
- `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:
|
||||
|
||||
@@ -185,6 +185,19 @@ protocol: BSSH
|
||||
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:
|
||||
|
||||
```
|
||||
@@ -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
|
||||
|
||||
```
|
||||
└── cr_W53Y93bB78.connection
|
||||
├── SHA256SUM
|
||||
├── SHA256SUM.sig
|
||||
├── chr_uVVuUITnVn.channel
|
||||
├── connection-recording-summary.json
|
||||
├── connection-recording.meta
|
||||
├── requests-inbound.data
|
||||
└── requests-outbound.data
|
||||
```
|
||||
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.
|
||||
- `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
|
||||
- `connection-recording.meta` is a plaintext file that contains metadata about the connection, including the connection id,
|
||||
requests seen, channel ids, and any errors seen. For each channel id listed, there should be a corresponding channel directory in the connection directory.
|
||||
- `connection-recording-summary.json` is a JSON file that contains a summary of the connection, including the connection id,
|
||||
start time, end time, bytes up, bytes down, and any errors encountered during recording the connection.
|
||||
- `requests-inbound.data` is a binary file containing all inbound SSH request messages transmitted for the connection.
|
||||
- `requests-outbound.data` is a binary file containing all outbound SSH request messages transmitted for the connection.
|
||||
|
||||
`connection-recording.meta` file example:
|
||||
|
||||
@@ -289,6 +289,7 @@ id: cr_W53Y93bB78
|
||||
requests: outbound
|
||||
requests: inbound
|
||||
channel: chr_uVVuUITnVn.channel
|
||||
error: error message would be appear here
|
||||
```
|
||||
|
||||
`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
|
||||
|
||||
```
|
||||
└── 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
|
||||
```
|
||||
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.
|
||||
- `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
|
||||
- `channel-recording.meta` is a plaintext file that contains metadata about the channel, including the channel id,
|
||||
inbound and outbound requests seen, and inbound and outbound messages seen.
|
||||
- `channel-recording-summary.json` is a JSON file that contains a summary of the channel, including the channel id,
|
||||
start time, end time, bytes up, bytes down, channel type, session program, subsystem name (if applicable), exec program (if applicable),
|
||||
and file transfer direction (if applicable).
|
||||
- `requests-inbound.data` is a binary file containing all inbound SSH request messages transmitted for the channel.
|
||||
- `requests-outbound.data` is a binary file containing all outbound SSH request messages transmitted for the channel.
|
||||
- `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:
|
||||
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
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(...).
|
||||
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.
|
||||
Reference in new issue
Block a user