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; 54], 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 decrypt( &self, epoch: &[u8; 4], lsn: u64, header_bytes: &[u8; 54], 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) -> WalEncryptionKey

Returns a duplicate of the value.

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

Performs copy-assignment from source.