Module crypto 

WAL payload encryption using AES-256-GCM.

Design:

• Header stays plaintext (needed for recovery scanning — magic, lsn, tenant_id)
• Payload is encrypted before CRC computation
• CRC covers the ciphertext (detects corruption of encrypted data)
• Nonce = [4-byte random epoch][8-byte LSN] — epoch is generated per WAL lifetime to prevent nonce reuse after snapshot restore or WAL truncation
• Additional Authenticated Data (AAD) = header bytes (binds ciphertext to its header)

On-disk format for encrypted payload:

[header(30B plaintext)] [ciphertext(payload_len bytes)] [auth_tag(16B)]

payload_len includes the 16-byte auth tag.

Structs

KeyRing

Key ring supporting dual-key reads for seamless key rotation.

WalEncryptionKey

AES-256-GCM key with a random per-lifetime epoch for nonce disambiguation.

Constants

AUTH_TAG_SIZE

AES-256-GCM auth tag size in bytes.

SEGMENT_ENVELOPE_MIN_SIZE

Minimum size of a valid encrypted envelope: preamble + AES-GCM auth tag.

SEGMENT_ENVELOPE_PREAMBLE_SIZE

Size of the segment envelope preamble in bytes.

Functions

decrypt_segment_envelope

Decrypt a segment envelope produced by encrypt_segment_envelope.

encrypt_segment_envelope

Encrypt plaintext into a self-describing segment envelope.