Struct EncryptionEngine 

pub struct EncryptionEngine { /* private fields */ }

Data-at-rest encryption engine.

Wraps AES-256-GCM-SIV with random nonces. Thread-safe (the cipher is Send + Sync and nonce generation uses OS randomness).

Implementations

impl EncryptionEngine

pub fn new(key: &[u8; 32]) -> Self

Create an encryption engine with the given 256-bit key.

The key must be exactly 32 bytes. Typically loaded from Kubernetes Secrets or the SOCHDB_ENCRYPTION_KEY env var.

pub fn from_key(key: &EncryptionKey) -> Self

Create an encryption engine from a zeroize-on-drop EncryptionKey.

Preferred over Self::new on the live path: the caller holds the key material in a wiping container rather than a bare [u8; 32].

pub fn disabled() -> Self

Create a disabled (passthrough) encryption engine.

encrypt() and decrypt() are identity operations when disabled.

pub fn is_enabled(&self) -> bool

Whether encryption is active.

pub fn encrypt(&self, plaintext: &[u8]) -> Result<Vec<u8>, EncryptionError>

Encrypt a plaintext block.

Returns [version(1) | nonce(12) | ciphertext+tag(N+16)].

Performance

~4 GB/s on x86_64 with AES-NI. The overhead is the 13-byte header plus 16-byte auth tag per block.

pub fn encrypt_with_aad( &self, plaintext: &[u8], aad: &[u8], ) -> Result<Vec<u8>, EncryptionError>

Encrypt a plaintext block, binding aad as additional authenticated data.

Returns [version(1) | nonce(12) | ciphertext+tag(N+16)]. The aad is NOT stored in the output — it is authenticated only, and the reader MUST reconstruct the identical aad (e.g. {format_version, db_uuid, dek_epoch, record_LSN}) from its own trusted state. Binding framing/ position as AAD is what prevents an attacker (or a corrupt/misdirected write) from reordering, duplicating, splicing, or downgrading WAL records — GCM-SIV alone authenticates only the isolated record body.

AAD scope is part of the on-disk format and cannot be widened later without a format break, so callers must commit to the full AAD tuple from the first encrypted byte written.

pub fn decrypt(&self, encrypted: &[u8]) -> Result<Vec<u8>, EncryptionError>

Decrypt an encrypted block produced by encrypt().

Validates the version byte and authentication tag.

pub fn decrypt_with_aad( &self, encrypted: &[u8], aad: &[u8], ) -> Result<Vec<u8>, EncryptionError>

Decrypt an encrypted block, verifying it against the same aad the writer bound via Self::encrypt_with_aad. A mismatched aad (e.g. a record that was moved to a different LSN/position) fails authentication exactly like a wrong key or tampered ciphertext — surfaced as EncryptionError::DecryptFailed, which callers MUST treat as a hard error, never as a clean end-of-stream.

pub fn encrypt_in_place( &self, buffer: &mut Vec<u8>, ) -> Result<(), EncryptionError>

Encrypt in-place for zero-copy WAL append.

Prepends the header to the buffer and encrypts the payload region. The buffer is resized to accommodate the header + auth tag.