Struct MasterKey 

pub struct MasterKey { /* private fields */ }

A 256-bit symmetric key that wipes its contents on drop.

Used as the SQLCipher key for the metadata store. The constructor only exposes generated keys and rehydration from existing bytes; the bytes themselves never leak through Display, Debug, or Serialize impls.

Examples

use evault_core::crypto::{ExposeSecret, MasterKey, MASTER_KEY_LEN};
let k = MasterKey::generate().expect("OS RNG should be available");
assert_eq!(k.bytes().expose_secret().len(), MASTER_KEY_LEN);

Implementations

impl MasterKey

pub fn generate() -> Result<Self, SecretError>

Generate a new key using the operating system’s secure RNG.

Errors

Returns SecretError::Backend if the OS RNG is unavailable, which is essentially fatal — every supported platform exposes one and failures here generally indicate a sandbox restriction or a hardware fault.

pub fn from_bytes(bytes: [u8; 32]) -> Self

Wrap pre-existing bytes (e.g. fetched from the OS keyring).

Prefer Self::generate for new keys.

pub const fn bytes(&self) -> &SecretBox<[u8; 32]>

Borrow the key bytes through a SecretBox.

Use ExposeSecret::expose_secret (re-exported as crate::crypto::ExposeSecret) to obtain the raw byte slice when passing it to the encryption layer.

pub fn to_hex_secret(&self) -> SecretString

Encode the key as lowercase hex.

SQLCipher accepts hex keys in the form PRAGMA key = "x'<hex>'". The returned SecretString is itself redacted in Debug output and zeroized on drop.

The staging buffer used to build the hex representation is explicitly zeroized before this function returns so that the plaintext hex form of the key cannot linger in heap memory.

Panics

This function never panics in practice: it constructs the hex representation from a fixed ASCII alphabet, so the std::str::from_utf8 check on the staging buffer always succeeds. The expect call exists only to encode the invariant structurally; clippy’s expect_used lint is allowed locally.

pub fn ct_eq(&self, other: &Self) -> bool

Compare two master keys in constant time.

[u8; N] uses bytewise memcmp which is allowed by the compiler to short-circuit on the first mismatching byte — a textbook timing side channel. This helper folds an OR-accumulator over every byte so that the running time depends only on the key length, not on the data.

Callers that need to compare key material must use this method instead of == on the bytes returned by bytes().expose_secret().

Examples

use evault_core::crypto::{MasterKey, MASTER_KEY_LEN};

let a = MasterKey::from_bytes([0xAB; MASTER_KEY_LEN]);
let b = MasterKey::from_bytes([0xAB; MASTER_KEY_LEN]);
let c = MasterKey::from_bytes([0xCD; MASTER_KEY_LEN]);
assert!(a.ct_eq(&b));
assert!(!a.ct_eq(&c));

Trait Implementations

impl Debug for MasterKey

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.