cbcrypto

Documentation

Index

• Constants
• Variables
• func Validate(r io.Reader) error
• type CBCWriter
  • func NewCBCWriter(w io.Writer, opts WriterOptions) (*CBCWriter, error)
  • func Open(rws io.ReadWriteSeeker, baseKey []byte) (*CBCWriter, error)
  • func (c *CBCWriter) AppendChunk(data io.Reader) error
• type CompressionType
• type ErrNotEncrypted
  • func (e *ErrNotEncrypted) Error() string
• type Header
• type KeyDerivationMethod
• type KeyProvider
• type Reader
  • func NewReader(r io.Reader, provider KeyProvider) (*Reader, error)
  • func (c *Reader) Read(p []byte) (int, error)
• type Version
• type WriterOptions

Constants

const CurrentVersion = Version1

CurrentVersion is the latest version of the cbcrypto file format which is supported by this package.

Variables

var MagicBytes = []byte("\x00Couchbase Encrypted\x00")

MagicBytes is the cbcrypto file format magic string: "\x00Couchbase Encrypted\x00"

Functions

func Validate

func Validate(r io.Reader) error

Validate checks if the provided reader starts with a valid cbcrypto header.

Types

type CBCWriter

type CBCWriter struct {
	// contains filtered or unexported fields
}

CBCWriter manages writing to a cbcrypto encrypted file.

func NewCBCWriter

func NewCBCWriter(w io.Writer, opts WriterOptions) (*CBCWriter, error)

NewCBCWriter initializes a new encrypted stream, writes the header to the provided writer, and returns a CBCWriter for appending data chunks.

A random 16-byte salt is generated for each new CBCwriter. This salt is included in the header, which is used as associated data (AD) for all encrypted chunks. When KBKDF or PBKDF2 key derivation is used, the salt is also incorporated into the key derivation context.

func Open

func Open(rws io.ReadWriteSeeker, baseKey []byte) (*CBCWriter, error)

Open initializes a CBCWriter for an existing cbcrypto file, allowing new chunks to be appended.

The provided 'rws' must be an io.ReadWriteSeeker containing an existing cbcrypto-formatted stream. Upon successful return, the seeker will be positioned at the end of the stream, ready for appending.

Open supports both v0 and v1 cbcrypto files. For files with key derivation, the key will be derived automatically based on the header's key derivation method.

func (*CBCWriter) AppendChunk

func (c *CBCWriter) AppendChunk(data io.Reader) error

AppendChunk compresses, encrypts, and appends a new data chunk.

type CompressionType

type CompressionType int

CompressionType defines the compression algorithm used in an encrypted file.

const (
	// These values are based on the cbcrypto encrypted file format specification.
	None CompressionType = iota
	Snappy
	ZLib
	GZip
	ZStd
	BZip2
)

type ErrNotEncrypted

type ErrNotEncrypted struct {
	Reason string
}

ErrNotEncrypted is returned when the file we were asked to read doesn't appear to be encrypted. This is determined based on the cbcrypto header.

func (*ErrNotEncrypted) Error

func (e *ErrNotEncrypted) Error() string

type Header

type Header struct {
	Version          Version
	Compression      CompressionType
	KeyDerivation    KeyDerivationMethod
	PBKDF2Iterations uint32 // Only valid when KeyDerivation == PasswordBasedKDF
	KeyID            string
	Salt             [saltSize]byte
}

Header represents the parsed metadata from the cbcrypto file header.

type KeyDerivationMethod

type KeyDerivationMethod uint8

KeyDerivationMethod specifies how the encryption key is derived from the provided base key.

const (
	// NoDerivation means the key is used directly without derivation (v0 behavior).
	NoDerivation KeyDerivationMethod = 0
	// KeyBasedKDF uses KBKDF HMAC/SHA2-256/Counter (introduced in v1).
	KeyBasedKDF KeyDerivationMethod = 1
	// PasswordBasedKDF uses PBKDF2 SHA2-256 (introduced in v1).
	PasswordBasedKDF KeyDerivationMethod = 2
)

type KeyProvider

type KeyProvider func(keyID string) ([]byte, error)

KeyProvider is a function that returns a data encryption key for a given key ID.

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Reader decrypts a cbcrypto stream on-demand.

func NewReader

func NewReader(r io.Reader, provider KeyProvider) (*Reader, error)

NewReader returns a Reader that decrypts and decompresses a cbcrypto stream on demand.

func (*Reader) Read

func (c *Reader) Read(p []byte) (int, error)

Read implements io.Reader by streaming decrypted plaintext from chunkSource one chunk at a time.

It will read until either:

1. The destination buffer 'p' is filled.

2. The current chunk is fully read.

3. EOF is reached.

NOTE: since at most one chunk is read at a time, many calls to Read may result in relatively small reads.

type Version

type Version = uint8

Version is the version of the cbcrypto file format.

const (
	// Version0 represents the initial version of the cbcrypto file format.
	Version0 Version = 0
	// Version1 adds support for key derivation (KBKDF and PBKDF2).
	Version1 Version = 1
)

type WriterOptions

type WriterOptions struct {
	// Compression specifies the compression algorithm to use for chunk data.
	Compression CompressionType

	// KeyID is the identifier for the encryption key (max 36 bytes).
	KeyID string

	// Key is the base key. When KeyDerivation is NoDerivation, this must be exactly 32 bytes.
	// When using KBKDF or PBKDF2, this can be any length and will be used to derive the actual encryption key.
	Key []byte

	// KeyDerivation specifies the key derivation method. Defaults to NoDerivation.
	//   - NoDerivation: use Key directly (must be 32 bytes)
	//   - KeyBasedKDF: derive key using KBKDF HMAC/SHA2-256/Counter
	//   - PasswordBasedKDF: derive key using PBKDF2 SHA2-256
	KeyDerivation KeyDerivationMethod

	// PBKDF2IterationExponent determines the number of PBKDF2 iterations when KeyDerivation is PasswordBasedKDF.
	// The iteration count is calculated as: 1024 * 2^PBKDF2IterationExponent
	// Must be in the range [0, 15]. Ignored for other key derivation methods.
	//
	// Examples:
	//   - 0 => 1024 iterations
	//   - 3 => 8192 iterations
	//   - 7 => 131072 iterations
	//
	// When using password-based key derivation, the spec recommends using "password" as the KeyID.
	PBKDF2IterationExponent uint8
}

WriterOptions holds the configuration for creating a CBCWriter.