diff --git a/website/content/docs/concepts/auditing.mdx b/website/content/docs/concepts/auditing.mdx index da2cfcd0e9..1a434ef90a 100644 --- a/website/content/docs/concepts/auditing.mdx +++ b/website/content/docs/concepts/auditing.mdx @@ -100,12 +100,254 @@ Boundary creates the top-level directory of the BSR as `.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). diff --git a/website/content/docs/operations/manage-recorded-sessions.mdx b/website/content/docs/operations/manage-recorded-sessions.mdx index fbf46b06bd..04529ced40 100644 --- a/website/content/docs/operations/manage-recorded-sessions.mdx +++ b/website/content/docs/operations/manage-recorded-sessions.mdx @@ -98,3 +98,67 @@ You can find all recorded sessions in the UI from the global scope. + +## 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).