Encryption

common.queueb.org/encryption provides a small authenticated-encryption API for complete byte slices.

Features

• AES-256-GCM authenticated encryption;
• a fresh random nonce generated internally for every message;
• a versioned envelope containing the nonce, ciphertext, and authentication tag;
• optional associated data that is authenticated but not stored;
• one generic error for malformed, unsupported, modified, or unauthenticated envelopes.

The API does not expose nonces, padding, block modes, or algorithm selection.

Requirements

• Go 1.26 or newer

Installation

go get common.queueb.org/encryption

Usage

key := encryption.GenerateKey()
box, err := encryption.New(key)
if err != nil {
	return err
}

context := []byte("record=example")
envelope := box.Seal(plaintext, context)

plaintext, err = box.Open(envelope, context)
if err != nil {
	return err
}

Store and distribute the key through an appropriate secret-management system. GenerateKey returns 32 random bytes; a password is not an encryption key and must not be passed directly to New.

The same key must not seal more than 2^32 messages. Applications own key storage, access control, distribution, rotation, and destruction.

Security boundary

Open authenticates the envelope header, ciphertext, and caller-supplied associated data before returning plaintext. Invalid input returns encryption.ErrInvalidEnvelope and no plaintext.

The module does not provide:

• password-based key derivation;
• key storage or KMS integration;
• streaming encryption;
• replay or rollback protection;
• in-memory key zeroization;
• compatibility with the former AES-CBC implementation.

The version 1 envelope layout and design rationale are documented in docs/design.md.

Compatibility

The v0.1.x line preserves the exported API and version 1 envelope decoder. A future incompatible envelope format will use a new explicit version rather than changing the meaning of version 1.

Development

Install pinned developer tools and run all local gates:

./hack/install-dev-tools.sh
./hack/verify.sh

See CONTRIBUTING.md for the development contract and SECURITY.md for private vulnerability reporting.

The file-based key example demonstrates decrypting a prepared envelope after reading a hex-encoded AES-256 key from the filesystem. Its committed key is public test data and must not be copied into production.

License

MIT. See LICENSE.