Struct WalEncryptionKey 

pub struct WalEncryptionKey { /* private fields */ }

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

The epoch is generated randomly at construction time. Each WAL lifetime (process start, snapshot restore, segment creation) gets a fresh epoch, ensuring that nonces are never reused even if LSNs restart from 1.

Implementations

impl WalEncryptionKey

pub fn from_bytes(key: &[u8; 32]) -> Result<Self>

Create from a 32-byte key with a fresh random epoch.

Returns an error if the OS RNG (getrandom) is unavailable. Without a fresh epoch we cannot guarantee nonce uniqueness across WAL lifetimes, so panicking would silently risk nonce reuse on RNG failure — better to surface it.

The key material is moved into a SecureKey, which mlocks it against swap and zeroizes it on drop.

pub fn with_epoch(key: &[u8; 32], epoch: [u8; 4]) -> Self

Create from a 32-byte key with a caller-supplied epoch.

Use this when reopening a WAL segment whose epoch was read from the on-disk preamble, so that the nonce is reconstructed identically to the nonce used at encryption time.

pub fn with_fresh_epoch(&self) -> Result<Self>

Produce a new key instance with the same key material but a fresh random epoch. Used when rolling to a new WAL segment — each segment gets its own epoch so the per-segment nonce space is independent.

The mlocked key allocation is shared with self via Arc; only the epoch differs, so no additional secret copy is made.

pub fn from_file(path: &Path) -> Result<Self>

Load key from a file (must contain exactly 32 bytes).

Before reading, the file is checked for:

• No symlinks (TOCTOU / path-traversal risk).
• Regular file (not a device, FIFO, or directory).
• Unix: no group or world access bits (mode & 0o077 == 0).
• Unix: file owner matches the current process UID.

pub fn encrypt( &self, lsn: u64, header_bytes: &[u8; 63], plaintext: &[u8], ) -> Result<Vec<u8>>

Encrypt a payload. Returns ciphertext + auth_tag (16 bytes appended).

• lsn: used to derive a deterministic nonce
• header_bytes: used as AAD (additional authenticated data)
• plaintext: the payload to encrypt

pub fn encrypt_aad( &self, lsn: u64, aad: &[u8], plaintext: &[u8], ) -> Result<Vec<u8>>

Encrypt with a caller-provided AAD slice (may be longer than HEADER_SIZE, e.g. preamble bytes prepended to the header).

pub fn epoch(&self) -> &[u8; 4]

The random epoch for this key instance.

pub fn derive_subkey(&self, domain: &[u8]) -> Result<[u8; 32]>

Derive a domain-separated application subkey without exposing the WAL encryption key itself. The result is stable across process lifetimes for the same configured key and deliberately excludes the random WAL nonce epoch.

pub fn decrypt( &self, epoch: &[u8; 4], lsn: u64, header_bytes: &[u8; 63], ciphertext: &[u8], ) -> Result<Vec<u8>>

Decrypt a payload. Input is ciphertext + auth_tag (16 bytes at end).

• epoch: must be the epoch that was used during encryption, read from the on-disk segment preamble — not self.epoch, which reflects the current in-memory lifetime and may differ after a restart.
• lsn: must match the LSN used during encryption
• header_bytes: must match the header used during encryption (AAD)
• ciphertext: the encrypted payload (includes 16-byte auth tag)

pub fn decrypt_aad( &self, epoch: &[u8; 4], lsn: u64, aad: &[u8], ciphertext: &[u8], ) -> Result<Vec<u8>>

Decrypt with a caller-provided AAD slice.

Trait Implementations

impl Clone for WalEncryptionKey

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.