Documentation
¶
Overview ¶
Package bsr is used to read and write boundary session recordings.
Index ¶
- Constants
- Variables
- func ChunkWalk(ctx context.Context, s *ChunkScanner, f ChunkReadFunc) error
- func NewChannelId() (string, error)
- func ReadMagic(r io.Reader) error
- func RegisterChunkType(p Protocol, t ChunkType, df DecodeChunkFunc) error
- func ValidByteSource(d ByteSource) bool
- func ValidChunkType(c ChunkType) bool
- func ValidCompression(c Compression) bool
- func ValidDirection(d Direction) bool
- func ValidEncryption(e Encryption) bool
- func ValidProtocol(p Protocol) bool
- type BaseChunk
- type ByteSource
- type Channel
- func (c *Channel) Close(ctx context.Context) error
- func (c Channel) EncodeSummary(_ context.Context, s any) error
- func (c *Channel) NewMessagesWriter(ctx context.Context, dir Direction) (io.Writer, error)
- func (c *Channel) NewRequestsWriter(ctx context.Context, dir Direction) (io.Writer, error)
- func (c *Channel) OpenMessageScanner(ctx context.Context, dir Direction) (*ChunkScanner, error)
- func (c *Channel) OpenRequestScanner(ctx context.Context, dir Direction) (*ChunkScanner, error)
- func (c Channel) WriteBinaryChecksum(_ context.Context, sum []byte, fname string) (int, error)
- func (c Channel) WriteMeta(_ context.Context, k, v string) (int, error)
- type ChannelRecordingMeta
- type ChannelSummary
- type Chunk
- type ChunkDecoder
- type ChunkEncoder
- type ChunkReadFunc
- type ChunkScanner
- type ChunkType
- type Compression
- type Connection
- func (c *Connection) Close(ctx context.Context) error
- func (c Connection) EncodeSummary(_ context.Context, s any) error
- func (c *Connection) NewChannel(ctx context.Context, meta *ChannelRecordingMeta) (*Channel, error)
- func (c *Connection) NewMessagesWriter(ctx context.Context, dir Direction) (io.Writer, error)
- func (c *Connection) NewRequestsWriter(ctx context.Context, dir Direction) (io.Writer, error)
- func (c *Connection) OpenChannel(ctx context.Context, chanId string) (*Channel, error)
- func (c Connection) WriteBinaryChecksum(_ context.Context, sum []byte, fname string) (int, error)
- func (c Connection) WriteMeta(_ context.Context, k, v string) (int, error)
- type ConnectionRecordingMeta
- type ConnectionSummary
- type DecodeChunkFunc
- type Direction
- type DynamicHost
- type DynamicHostCatalog
- type Encryption
- type EndChunk
- type HeaderChunk
- type Option
- type Protocol
- type Scope
- type Session
- func (s *Session) Close(ctx context.Context) error
- func (c Session) EncodeSummary(_ context.Context, s any) error
- func (s *Session) NewConnection(ctx context.Context, meta *ConnectionRecordingMeta) (*Connection, error)
- func (s *Session) OpenConnection(ctx context.Context, connId string) (*Connection, error)
- func (c Session) WriteBinaryChecksum(_ context.Context, sum []byte, fname string) (int, error)
- func (c Session) WriteMeta(_ context.Context, k, v string) (int, error)
- type SessionMeta
- type SessionRecordingMeta
- type SessionSummary
- type StaticCredentialStore
- type StaticHost
- type StaticHostCatalog
- type StaticJsonCredential
- type StaticSshPrivateKeyCredential
- type StaticUsernamePasswordCredential
- type Target
- type Timestamp
- type User
- type VaultCredentialStore
- type VaultGenericLibrary
- type VaultSshCertificateLibrary
- type Worker
Constants ¶
const ( // ChannelIdPrefix is the prefix for the channel recording id. ChannelIdPrefix = globals.ChannelRecordingPrefix )
const ( // Magic is the magic string / magic number / file signature used to // identify a BSR data file. // // See: https://en.wikipedia.org/wiki/File_format#Magic_number Magic magic = magic("\x89BSR\r\n\x1a\n") )
Variables ¶
var ( // ErrUnknown represents an unknown error ErrUnknown = errors.New("unknown error") // ErrInvalidParameter represents an invalid parameter error ErrInvalidParameter = errors.New("invalid parameter") // ErrBsrKeyPersistenceFailure indicates a failure in persisting BSR encryption keys ErrBsrKeyPersistenceFailure = errors.New("could not persist BSR keys") ErrSummaryUnavailable = errors.New("summary not available") // ErrSignatureVerification indicates a failure in verifying a signature ErrSignatureVerification = errors.New("could not verify signature") // ErrNotSupported represents an operation that is not supported for a // particular protocol. ErrNotSupported = errors.New("not supported by protocol") // ErrAlreadyRegistered is an error with registering chunk decoder functions. ErrAlreadyRegistered = errors.New("chunk type already registered") // ErrEndChunkNotEmpty indicates a malformed END chunk. ErrEndChunkNotEmpty = errors.New("end chunk not empty") // ErrChunkDecode indicates an error when decoding a chunk. ErrChunkDecode = errors.New("error decoding chunk") // ErrInvalidMagic is used when a binary bsr file is missing the magic string. ErrInvalidMagic = errors.New("invalid magic string") // ErrChecksum indicates that a checksum did not match. ErrChecksum = errors.New("computed checksum did NOT match") )
Functions ¶
func ChunkWalk ¶
func ChunkWalk(ctx context.Context, s *ChunkScanner, f ChunkReadFunc) error
ChunkWalk will step through the chunks returned by the ChunkScanner and call the provided ChunkReadFunc f for each. If f returns an error or a non io.EOF error is returned from the scanner the walk will terminate early. Otherwise the walk will terminate once io.EOF is reached.
func NewChannelId ¶
NewChannelId generates an id for a channel recording.
func ReadMagic ¶
ReadMagic attempts to read the magic string from the given io.Reader. If it is unable to read enough bytes, or if the magic string does not match an error is returned.
func RegisterChunkType ¶
func RegisterChunkType(p Protocol, t ChunkType, df DecodeChunkFunc) error
RegisterChunkType registers a DecodeChunkFunc for the given Protocol and ChunkType. A given Protocol and ChunkType can only have one decode function registered.
func ValidByteSource ¶
func ValidByteSource(d ByteSource) bool
ValidByteSource checks if a given ByteSource is valid.
func ValidChunkType ¶
ValidChunkType checks ifa given ChunkType is valid.
func ValidCompression ¶
func ValidCompression(c Compression) bool
ValidCompression checks if a given Compression is valid.
func ValidDirection ¶
ValidDirection checks if a given Direction is valid.
func ValidEncryption ¶
func ValidEncryption(e Encryption) bool
ValidEncryption checks if a given Encryption is valid.
func ValidProtocol ¶
ValidProtocol checks if a given Protocol is valid.
Types ¶
type BaseChunk ¶
type BaseChunk struct { Protocol Protocol Direction Direction Timestamp *Timestamp Type ChunkType // contains filtered or unexported fields }
BaseChunk contains the common fields of all chunk types.
func NewBaseChunk ¶
func NewBaseChunk(ctx context.Context, p Protocol, d Direction, t *Timestamp, typ ChunkType) (*BaseChunk, error)
NewBaseChunk creates a BaseChunk.
func (*BaseChunk) GetDirection ¶
GetDirection returns the direction of the data in the chunk.
func (*BaseChunk) GetProtocol ¶
GetProtocol returns the protocol of the recorded data.
func (*BaseChunk) GetTimestamp ¶
GetTimestamp returns the timestamp of a Chunk.
type ByteSource ¶
type ByteSource uint8
ByteSource identifies whether bytes are flowing from the user to target (client) or target to user (server)
const ( UnknownByteSource ByteSource = iota Client Server )
ByteDirections
func (ByteSource) String ¶
func (d ByteSource) String() string
type Channel ¶
type Channel struct { Meta *ChannelRecordingMeta // contains filtered or unexported fields }
Channel is a container in a bsr for a specific channel in a session container. It contains the files for the recorded channel.
func (Channel) EncodeSummary ¶
EncodeSummary writes a new line terminated key : value pair to the container's summary file
func (*Channel) NewMessagesWriter ¶
NewMessagesWriter creates a writer for recording channel messages.
func (*Channel) NewRequestsWriter ¶
NewRequestsWriter creates a writer for recording channel requests.
func (*Channel) OpenMessageScanner ¶
OpenMessageScanner opens a ChunkScanner for a channel's recorded messages.
func (*Channel) OpenRequestScanner ¶
OpenRequestScanner opens a ChunkScanner for a channel's recorded requests.
func (Channel) WriteBinaryChecksum ¶
WriteBinaryChecksum writes a checksum for a binary file to the checksum file.
type ChannelRecordingMeta ¶
ChannelRecordingMeta contains metadata about a channel in a BSR.
type ChannelSummary ¶
type ChannelSummary struct { Id string ConnectionRecordingId string StartTime time.Time EndTime time.Time BytesUp uint64 BytesDown uint64 ChannelType string }
ChannelSummary encapsulates data for a channel, including its id, channel type, start/end time using a monotonic clock, and the bytes up/ down seen on this channel
type Chunk ¶
type Chunk interface { // GetLength returns the length of the chunk data. GetLength() uint32 // GetProtocol returns the protocol of the recorded data. GetProtocol() Protocol // GetType returns the chunk type. GetType() ChunkType // GetDirection returns the direction of the data in the chunk. GetDirection() Direction // GetTimestamp returns the timestamp of a Chunk. GetTimestamp() *Timestamp // MarshalData serializes the data portion of a chunk. MarshalData(context.Context) ([]byte, error) }
Chunk is a section of a bsr data file.
type ChunkDecoder ¶
type ChunkDecoder struct {
// contains filtered or unexported fields
}
ChunkDecoder is used to decode the data read from an io.Reader into Chunks.
func NewChunkDecoder ¶
NewChunkDecoder creates a ChunkDecoder that can decode the data read from the given io.Reader. Supports the WithKeys option which will be used when support for encrypted chunks is added.
func (*ChunkDecoder) Decode ¶
func (d *ChunkDecoder) Decode(ctx context.Context) (Chunk, error)
Decode will read from the io.Reader and return the next Chunk that it decodes. If the io.Reader reaches EOF, Decode will return an error of io.EOF. Note that this is not a wrapped error so it can be checked for with err == io.EOF like with most io.Readers. If there is an unexpected error while decoding, such as an unsupported chunk type or corrupted data, an ErrChunkDecode error will be returned. This will be a wrapped error and should be checked for with errors.Is.
type ChunkEncoder ¶
type ChunkEncoder struct {
// contains filtered or unexported fields
}
ChunkEncoder will encode a chunk and write it to the writer. It will compress the chunk data based on the compression.
func NewChunkEncoder ¶
func NewChunkEncoder(ctx context.Context, w io.Writer, c Compression, e Encryption) (*ChunkEncoder, error)
NewChunkEncoder creates a ChunkEncoder.
type ChunkReadFunc ¶
ChunkReadFunc is a function that can be used by ChunkWalk to process a Chunk.
type ChunkScanner ¶
type ChunkScanner struct {
// contains filtered or unexported fields
}
ChunkScanner can be used to read a Chunk at a time.
func NewChunkScanner ¶
NewChunkScanner creates a ChunkScanner. The scanner will calculate a rolling sha256sum of all of the chunks that have been read. Supports the following options:
- WithSha256Sum: This is used to provide an expected sha256sum. Once the scanner encounters an END chunk or an io.EOF error, it will compare the calculated sha256sum against this sum. If the sums do not match, ErrChecksum will be returned.
Other options are passed through to the ChunkDecoder used by the scanner.
func (*ChunkScanner) Close ¶
func (cs *ChunkScanner) Close() error
Close closes the scanner's reader.
func (*ChunkScanner) Scan ¶
func (cs *ChunkScanner) Scan(ctx context.Context) (Chunk, error)
Scan reads the next Chunk from the reader. If the scanner was created using WithSha256Sum, the calculated sum will be compared to the provided sum when the scanner encounters either an END Chunk, or an io.EOF error. If the sums do not match, ErrChecksum will be returned.
type Compression ¶
type Compression uint8
Compression is used to identify the compression used for the data in chunks.
const ( NoCompression Compression = iota GzipCompression )
Supported compression methods.
func (Compression) String ¶
func (c Compression) String() string
type Connection ¶
type Connection struct { Meta *ConnectionRecordingMeta // contains filtered or unexported fields }
Connection is a container in a bsr for a specific connection in a session container. It contains the files for the recorded connection.
func (*Connection) Close ¶
func (c *Connection) Close(ctx context.Context) error
Close closes the Connection container.
func (Connection) EncodeSummary ¶
EncodeSummary writes a new line terminated key : value pair to the container's summary file
func (*Connection) NewChannel ¶
func (c *Connection) NewChannel(ctx context.Context, meta *ChannelRecordingMeta) (*Channel, error)
NewChannel creates a Channel container for a given channel id.
func (*Connection) NewMessagesWriter ¶
NewMessagesWriter creates a writer for recording channel messages.
func (*Connection) NewRequestsWriter ¶
NewRequestsWriter creates a writer for recording connection requests.
func (*Connection) OpenChannel ¶
OpenChannel will open and validate a BSR channel
func (Connection) WriteBinaryChecksum ¶
WriteBinaryChecksum writes a checksum for a binary file to the checksum file.
type ConnectionRecordingMeta ¶
type ConnectionRecordingMeta struct { Id string // contains filtered or unexported fields }
ConnectionRecordingMeta contains metadata about a connection in a BSR.
type ConnectionSummary ¶
type ConnectionSummary struct { Id string ChannelCount uint64 StartTime time.Time EndTime time.Time BytesUp uint64 BytesDown uint64 Errors error }
ConnectionSummary encapsulates data for a connection, including its connection id, channel count, start/end time using a monotonic clock, and the aggregate bytes up/ down of its channels
type DecodeChunkFunc ¶
DecodeChunkFunc is a function that given a BaseChunk and the data portion of a chunk, will decode the data into a Chunk.
type Direction ¶
type Direction uint8
Direction identifies the directionality of the data captured in the chunk.
type DynamicHost ¶
type DynamicHost struct { PublicId string Catalog DynamicHostCatalog Name string // optional field Description string // optional field ExternalId string ExternalName string // optional field }
DynamicHost contains information about the dynamic host for this session
type DynamicHostCatalog ¶
type DynamicHostCatalog struct { PublicId string ProjectId string Name string // optional field Description string // optional field PluginId string Attributes string }
DynamicHostCatalog contains information about the dynamic host catalog for this session
type Encryption ¶
type Encryption uint8
Encryption is used to identify the encryption used for the data in chunks.
const (
NoEncryption Encryption = iota
)
Supported encryption methods.
func (Encryption) String ¶
func (e Encryption) String() string
type EndChunk ¶
type EndChunk struct {
*BaseChunk
}
EndChunk identifies the end of the chunks in a BSR data file. An EndChunk in a bsr data file is represented as:
uint32 length 4 bytes uint32 protocol 4 bytes uint32 chunk_type 4 bytes uint8 direction 1 byte timest timestamp 12 bytes data 0 bytes uint32 crc 4 bytes
type HeaderChunk ¶
type HeaderChunk struct { *BaseChunk Compression Compression Encryption Encryption SessionId string }
HeaderChunk is the first chunk in a BSR data file. A HeaderChunk in a bsr data file is represented as:
uint32 length 4 bytes uint32 protocol 4 bytes uint32 chunk_type 4 bytes uint8 direction 1 byte timest timestamp 12 bytes uint8 compression 1 byte uint8 encryption 1 byte session_id variable uint32 crc 4 bytes
func NewHeader ¶
func NewHeader(ctx context.Context, p Protocol, d Direction, t *Timestamp, c Compression, e Encryption, sessionId string) (*HeaderChunk, error)
NewHeader creates a HeaderChunk.
func (*HeaderChunk) MarshalData ¶
func (h *HeaderChunk) MarshalData(_ context.Context) ([]byte, error)
MarshalData serializes a HeaderChunk.
type Option ¶
type Option func(*options)
Option - how Options are passed as arguments
func WithSha256Sum ¶
WithSha256Sum is used to provide a hex encoded SHA256SUM.
func WithSupportsMultiplex ¶
WithSupportsMultiplex is used indicate that a protocol supports multiplexing and therefore a BSR can contain Channels.
type Protocol ¶
type Protocol string
Protocol identifies the protocol of the data captured in a chunk.
type Scope ¶
type Scope struct { PublicId string Name string // optional Description string // optional Type string ParentId string // optional PrimaryAuthMethodId string // optional }
Scope contains information about the scope of a Boundary domain object
type Session ¶
type Session struct { Meta *SessionRecordingMeta SessionMeta *SessionMeta // contains filtered or unexported fields }
Session is the top level container in a bsr that contains the files for a recorded session.
func NewSession ¶
func NewSession(ctx context.Context, meta *SessionRecordingMeta, sessionMeta *SessionMeta, f storage.FS, keys *kms.Keys, options ...Option) (*Session, error)
NewSession creates a Session container for a given session id.
func OpenSession ¶
func OpenSession(ctx context.Context, sessionRecordingId string, f storage.FS, keyUnwrapFn kms.KeyUnwrapCallbackFunc) (*Session, error)
OpenSession retrieves a BSR from storage using the sessionRecordingId and initializes it for reading. Encryption keys necessary for checking signed files will be unwrapped using the keyUnwrapFn Signature and checksum files will then be verified. Fields on the underlying container will be populated so that the returned Session can be used for BSR playback and conversion to formats such as asciinema
func (Session) EncodeSummary ¶
EncodeSummary writes a new line terminated key : value pair to the container's summary file
func (*Session) NewConnection ¶
func (s *Session) NewConnection(ctx context.Context, meta *ConnectionRecordingMeta) (*Connection, error)
NewConnection creates a Connection container for a given connection id.
func (*Session) OpenConnection ¶
OpenConnection will open and validate a BSR connection
func (Session) WriteBinaryChecksum ¶
WriteBinaryChecksum writes a checksum for a binary file to the checksum file.
type SessionMeta ¶
type SessionMeta struct { PublicId string Endpoint string User *User Target *Target Worker *Worker // StaticHost and DynamicHost are mutually exclusive StaticHost *StaticHost DynamicHost *DynamicHost StaticJSONCredentials []StaticJsonCredential StaticUsernamePasswordCredentials []StaticUsernamePasswordCredential StaticSshPrivateKeyCredentials []StaticSshPrivateKeyCredential VaultGenericLibraries []VaultGenericLibrary VaultSshCertificateLibraries []VaultSshCertificateLibrary }
SessionMeta contains metadata about a session in a BSR.
func TestSessionMeta ¶
func TestSessionMeta(s string) *SessionMeta
type SessionRecordingMeta ¶
type SessionRecordingMeta struct { Id string Protocol Protocol // contains filtered or unexported fields }
SessionRecordingMeta contains metadata about a session in a BSR. Most fields are written to the meta file as k:v pairs Slice fields are written to the meta file as id_k:v Nested slice fields are written as parentId_parentKey_id_k:v
func TestSessionRecordingMeta ¶
func TestSessionRecordingMeta(s string, p Protocol) *SessionRecordingMeta
type SessionSummary ¶
type SessionSummary struct { Id string ConnectionCount uint64 StartTime time.Time EndTime time.Time Errors error }
SessionSummary encapsulates data for a session, including its session id, connection count, and start/end time using a monotonic clock
type StaticCredentialStore ¶
type StaticCredentialStore struct { PublicId string ProjectId string Name string // optional field Description string // optional field }
StaticCredentialStore represents a static credential store used for this session
type StaticHost ¶
type StaticHost struct { PublicId string Catalog StaticHostCatalog Name string // optional field Description string // optional field Address string }
StaticHost contains information about the static host for this session
type StaticHostCatalog ¶
type StaticHostCatalog struct { PublicId string ProjectId string Name string // optional field Description string // optional field }
StaticHostCatalog contains information about the static host catalog for this session
type StaticJsonCredential ¶
type StaticJsonCredential struct { PublicId string Name string // optional field Description string // optional field ObjectHmac []byte Purposes []string CredentialStore StaticCredentialStore }
StaticJsonCredential represents a static json credential used for this session
type StaticSshPrivateKeyCredential ¶
type StaticSshPrivateKeyCredential struct { PublicId string Name string // optional field Description string // optional field Username string PrivateKeyHmac []byte PrivateKeyPassphraseHmac []byte // optional field Purposes []string CredentialStore StaticCredentialStore }
StaticSshPrivateKeyCredential represents a Static Ssh private key credential used for this session
type StaticUsernamePasswordCredential ¶
type StaticUsernamePasswordCredential struct { PublicId string Name string // optional field Description string // optional field Username string PasswordHmac []byte Purposes []string CredentialStore StaticCredentialStore }
StaticUsernamePasswordCredential represents a Static username password credential used for this session
type Target ¶
type Target struct { PublicId string Scope Scope Name string // optional field Description string // optional field DefaultPort uint32 DefaultClientPort uint32 // optional field SessionMaxSeconds uint32 SessionConnectionLimit int32 WorkerFilter string // optional field EgressWorkerFilter string // optional field IngressWorkerFilter string // optional field EnableSessionRecording bool StorageBucketId string }
Target contains information about the target for this session
type Timestamp ¶
Timestamp is a time.Time that can be marshaled/unmarshaled to/from a bsr data file. A Timestamp in a bsr data file is represented as:
uint64 seconds 8 bytes uint32 nanoseconds 4 bytes
Where seconds is the number of seconds since unix epoch (Jan 1, 1970 00:00:00) and nanoseconds are the number of nanoseconds since the last second. This means the BSR cannot have times earlier than unix epoch.
type User ¶
type User struct { PublicId string Scope Scope Name string // optional field Description string // optional field }
User contains information about user who initiated this session
type VaultCredentialStore ¶
type VaultCredentialStore struct { PublicId string ProjectId string Name string // optional field Description string // optional field VaultAddress string Namespace string TlsServerName string TlsSkipVerify bool WorkerFilter string // optional field }
VaultCredentialStore represents a Vault credential store used for this session
type VaultGenericLibrary ¶
type VaultGenericLibrary struct { PublicId string Name string // optional field Description string // optional field VaultPath string HttpMethod string HttpRequestBody []byte // optional field CredentialType string Purposes []string CredentialStore VaultCredentialStore }
VaultGenericLibrary contains information about the Vault library used for this session
type VaultSshCertificateLibrary ¶
type VaultSshCertificateLibrary struct { PublicId string Name string // optional field Description string // optional field VaultPath string Username string KeyType string KeyBits int Ttl string // optional field CriticalOptions []byte // optional field Extensions []byte // optional field CredentialType string // optional field Purposes []string CredentialStore VaultCredentialStore }
VaultSshCertificateLibrary contains information about a Vault Ssh Cert library for this session
Source Files
¶
Directories
¶
Path | Synopsis |
---|---|
Package convert provides functions for converting BSR data into other formats.
|
Package convert provides functions for converting BSR data into other formats. |
internal/asciicast
Package asciicast defines structs to ease the creation of asciicast files.
|
Package asciicast defines structs to ease the creation of asciicast files. |
gen
|
|
internal
|
|
checksum
Package checksum provides a wrapper to compute a checksum on a writable file while it is being written to, and record the final checksum when the file is closed.
|
Package checksum provides a wrapper to compute a checksum on a writable file while it is being written to, and record the final checksum when the file is closed. |
fstest
Package fstest provides test implementations of the fs interfaces.
|
Package fstest provides test implementations of the fs interfaces. |
journal
Package journal provides a writer that uses a journal file to aide in recovery.
|
Package journal provides a writer that uses a journal file to aide in recovery. |
sign
Package sign provides wrappers to compute a signature of data written to an io.Writer
|
Package sign provides wrappers to compute a signature of data written to an io.Writer |
Package ssh defines chunk types for recordings of the ssh protocol.
|
Package ssh defines chunk types for recordings of the ssh protocol. |