Skip to content

Commit a8257a7

Browse files
Merge pull request #4549 from hashicorp/backport/irindos-update-bsr-detail/eagerly-beloved-civet
This pull request was automerged via backport-assistant
2 parents 17da2a0 + 86ba76d commit a8257a7

File tree

2 files changed

+82
-83
lines changed

2 files changed

+82
-83
lines changed

website/content/docs/concepts/auditing.mdx

Lines changed: 77 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -101,19 +101,40 @@ Any session recording metadata that is attached to the storage bucket is deleted
101101
The BSR (Boundary Session Recording) defines a hierarchical directory structure of files and a binary file format.
102102
It contains all the data transmitted between a user and a target during a single session.
103103

104-
Boundary creates the top-level directory of the BSR as `<sessionID>.bsr`. This top level directory contains session summary information and subdirectories for connections.
104+
Boundary creates the top-level directory of the BSR as `<sessionRecordingID>.bsr`. This top level directory contains session summary
105+
information and subdirectories for connections.
105106

106107
A BSR connections directory contains a summary of connections, as well as inbound and outbound requests.
107108
If you use a multiplexed protocol, there are subdirectories for the channels.
108109

110+
Every directory contains a SHA256SUMS and SHA256SUMS.sig file, to be used for cryptographically verifying the contents of
111+
that directory. The SHA256SUMS file contains rows of file names paired with a checksum for file contents. The
112+
SHA256SUMS.sign is a copy of the SHA256SUMS file, signed with the BSR’s private key. For more information on verifying a
113+
session recording, refer to [Validating the integrity of session recordings](/boundary/docs/operations/session-recordings/validate-session-recordings).
114+
115+
The example BSR below is for a multiplexed session recording with the ID `sr_iNCdGSREeX`. The session recording contains one connection,
116+
`cr_3bB78W53Y9`. Connection `cr_3bB78W53Y9` contains two channels, `chr_VUnVuVnITu` and `chr_nITuVUnVuV`.
117+
The files in each directory are explained in the following sections.
118+
109119
```
110120
└── sr_iNCdGSREeX.bsr
111121
├── SHA256SUM
112122
├── SHA256SUM.sig
113123
├── bsrKey.pub
124+
├── pubKeyBsrSignature.sign
125+
├── pubKeySelfSignature.sign
126+
├── session-meta.json
127+
├── session-recording-summary.json
128+
├── session-recording.meta
129+
├── wrappedBsrKey
130+
├── wrappedPrivKey
114131
├── cr_3bB78W53Y9.connection
115132
│ ├── SHA256SUM
116133
│ ├── SHA256SUM.sig
134+
│ ├── connection-recording-summary.json
135+
│ ├── connection-recording.meta
136+
│ ├── requests-inbound.data
137+
│ ├── requests-outbound.data
117138
│ ├── chr_VUnVuVnITu.channel
118139
│ │ ├── SHA256SUM
119140
│ │ ├── SHA256SUM.sig
@@ -132,50 +153,29 @@ If you use a multiplexed protocol, there are subdirectories for the channels.
132153
│ │ ├── messages-outbound.data
133154
│ │ ├── requests-inbound.data
134155
│ │ └── requests-outbound.data
135-
│ ├── connection-recording-summary.json
136-
│ ├── connection-recording.meta
137-
│ ├── requests-inbound.data
138-
│ └── requests-outbound.data
139-
├── cr_W53Y93bB78.connection
140-
│ ├── SHA256SUM
141-
│ ├── SHA256SUM.sig
142-
│ ├── chr_uVVuUITnVn.channel
143-
│ │ ├── SHA256SUM
144-
│ │ ├── SHA256SUM.sig
145-
│ │ ├── channel-recording-summary.json
146-
│ │ ├── channel-recording.meta
147-
│ │ ├── messages-inbound.data
148-
│ │ ├── messages-outbound.data
149-
│ │ ├── requests-inbound.data
150-
│ │ └── requests-outbound.data
151-
│ ├── connection-recording-summary.json
152-
│ ├── connection-recording.meta
153-
│ ├── requests-inbound.data
154-
│ └── requests-outbound.data
155-
├── pubKeyBsrSignature.sign
156-
├── pubKeySelfSignature.sign
157-
├── session-meta.json
158-
├── session-recording-summary.json
159-
├── session-recording.meta
160-
├── wrappedBsrKey
161-
└── wrappedPrivKey
156+
│ └──
157+
└──
158+
159+
162160
```
163161

164162
### BSR Session folder
165-
```
166-
└── sr_iNCdGSREeX.bsr
167-
├── SHA256SUM
168-
├── SHA256SUM.sig
169-
├── bsrKey.pub
170-
├── cr_3bB78W53Y9.connection
171-
├── pubKeyBsrSignature.sign
172-
├── pubKeySelfSignature.sign
173-
├── session-meta.json
174-
├── session-recording-summary.json
175-
├── session-recording.meta
176-
├── wrappedBsrKey
177-
└── wrappedPrivKey
178-
```
163+
A BSR session folder contains the following files:
164+
- `SHA256SUM.sig` is a plaintext file that contains rows of file names paired with a checksum for file contents.
165+
- `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
166+
- `bsrKey.pub` is the public ed25519 key.
167+
- `pubKeySelfSignature.sign` is a self-signature of the plaintext public ed25519 key created with its private key.
168+
- `pubKeyBsrSignature.sign` is a signature of the plaintext public ed25519 key created with the BSR key.
169+
- `wrappedBsrKey` is the BSR key wrapped by the external KMS AES-GCM key that you configure.
170+
- `wrappedPrivKey` is the private ed25519 key wrapped by the external KMS AES-GCM key that you configure.
171+
- `session-meta.json` is a JSON file that contains metadata about the session, including the session id, endpoint,
172+
user, target, host, worker, and credentials used to access the target. The intention of this file is to provide all information
173+
relevant to the recorded session so that the BSR provides a complete snapshot of a session even in the absence of the Boundary
174+
control plane.
175+
- `session-recording.meta` is a plaintext file that contains metadata about the session, including the session id, protocol,
176+
and a connection ids. For each connection id listed, there should be a corresponding connection directory in the session directory.
177+
- `session-recording-summary.json` is a JSON file that contains a summary of the session recording, including the session id, connection count,
178+
start time, end time, and any errors encountered during recording of the session.
179179

180180
`session-recording.meta` file example:
181181

@@ -185,6 +185,19 @@ protocol: BSSH
185185
connection: cr_3bB78W53Y9.connection
186186
```
187187

188+
`session-recording-summary.json` file example:
189+
190+
```
191+
{
192+
"Id": "sr_iNCdGSREeX",
193+
"ConnectionCount": 1,
194+
"StartTime": "2023-09-19T15:05:39.343307163Z",
195+
"EndTime": "2023-09-19T15:08:02.953159598Z",
196+
"Errors": ""
197+
}
198+
199+
```
200+
188201
`session-meta.json` file example:
189202

190203
```
@@ -258,29 +271,16 @@ connection: cr_3bB78W53Y9.connection
258271
}
259272
```
260273

261-
`session-recording.json` file example:
262-
263-
```
264-
id: sr_iNCdGSREeX
265-
protocol: BSSH
266-
connection: cr_3bB78W53Y9.connection
267-
```
268-
269-
`SHA256SUM` and `SHA256SUM.sig` files are used for cryptographically verifying the contents of this directory.
270-
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).
271-
272274
### BSR Connection folder
273-
274-
```
275-
└── cr_W53Y93bB78.connection
276-
├── SHA256SUM
277-
├── SHA256SUM.sig
278-
├── chr_uVVuUITnVn.channel
279-
├── connection-recording-summary.json
280-
├── connection-recording.meta
281-
├── requests-inbound.data
282-
└── requests-outbound.data
283-
```
275+
A BSR connection folder contains the following files:
276+
- `SHA256SUM.sig` is a plaintext file that contains rows of file names paired with a checksum for file contents.
277+
- `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
278+
- `connection-recording.meta` is a plaintext file that contains metadata about the connection, including the connection id,
279+
requests seen, channel ids, and any errors seen. For each channel id listed, there should be a corresponding channel directory in the connection directory.
280+
- `connection-recording-summary.json` is a JSON file that contains a summary of the connection, including the connection id,
281+
start time, end time, bytes up, bytes down, and any errors encountered during recording the connection.
282+
- `requests-inbound.data` is a binary file containing all inbound SSH request messages transmitted for the connection.
283+
- `requests-outbound.data` is a binary file containing all outbound SSH request messages transmitted for the connection.
284284

285285
`connection-recording.meta` file example:
286286

@@ -289,6 +289,7 @@ id: cr_W53Y93bB78
289289
requests: outbound
290290
requests: inbound
291291
channel: chr_uVVuUITnVn.channel
292+
error: error message would be appear here
292293
```
293294

294295
`connection-recording-summary.json` file example:
@@ -305,22 +306,19 @@ channel: chr_uVVuUITnVn.channel
305306
}
306307
```
307308

308-
`*.data` files are binary files containing all data transmitted during a session.
309-
`SHA256SUM` and `SHA256SUM.sig` files are used for cryptographically verifying the contents of this directory.
310-
311309
### BSR Channel folder
312-
313-
```
314-
└── chr_uVVuUITnVn.channel
315-
├── SHA256SUM
316-
├── SHA256SUM.sig
317-
├── channel-recording-summary.json
318-
├── channel-recording.meta
319-
├── messages-inbound.data
320-
├── messages-outbound.data
321-
├── requests-inbound.data
322-
└── requests-outbound.data
323-
```
310+
A BSR connection folder contains the following files:
311+
- `SHA256SUM.sig` is a plaintext file that contains rows of file names paired with a checksum for file contents.
312+
- `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
313+
- `channel-recording.meta` is a plaintext file that contains metadata about the channel, including the channel id,
314+
inbound and outbound requests seen, and inbound and outbound messages seen.
315+
- `channel-recording-summary.json` is a JSON file that contains a summary of the channel, including the channel id,
316+
start time, end time, bytes up, bytes down, channel type, session program, subsystem name (if applicable), exec program (if applicable),
317+
and file transfer direction (if applicable).
318+
- `requests-inbound.data` is a binary file containing all inbound SSH request messages transmitted for the channel.
319+
- `requests-outbound.data` is a binary file containing all outbound SSH request messages transmitted for the channel.
320+
- `messages-inbound.data` is a binary file containing all inbound SSH data transmitted for the channel.
321+
- `messages-outbound.data` is a binary file containing all outbound SSH data transmitted for the channel.
324322

325323
`channel-recording.meta` file example:
326324

@@ -353,7 +351,4 @@ requests: inbound
353351
}
354352
```
355353

356-
`*.data` files are binary files containing all data transmitted during a session.
357-
`SHA256SUM` and `SHA256SUM.sig` files are used for cryptographically verifying the contents of this directory.
358-
359354
For more information, refer to the [overview of configuring session recording](/boundary/docs/configuration/session-recording).

website/content/docs/operations/session-recordings/validate-session-recordings.mdx

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,4 +56,8 @@ Follow these steps to validate a session recording:
5656
1. Unwrap `wrappedBsrKey` using the external KMS you configured to retrieve the BSR key.
5757
2. Unwrap `wrappedPrivKey` using the external KMS you configured to retrieve the private key.
5858
3. Use the BSR key or the private key to verify the `bsrKey.pub` key using `go-kms-wrapping` HmacSha256(...).
59-
4. When the key is verified, use the `bsrKey.pub` key to verify the BSR SHA256SUM file using `go-kms-wrapping` ed25519.Sign(...).
59+
4. When the key is verified, use the `bsrKey.pub` key to verify the BSR SHA256SUM.sig file using `go-kms-wrapping` ed25519.Sign(...).
60+
5. After verifying the SHA256SUM.sig file, use the `sha256` commandline tool to verify BSR checksums using `sha256sum -c SHA256SUM`.
61+
6. Examine the *.meta files in the directory. For session-recording.meta, every connection logged in the meta file should
62+
correspond to a connection folder in the directory. For a connection-recording.meta, every channel logged in the meta file should
63+
correspond to a channel folder in the directory.

0 commit comments

Comments
 (0)