Struct KeyVaultBuilder

Source

pub struct KeyVaultBuilder { /* private fields */ }

Expand description

Fluent builder for KeyVault.

The builder is the only way to construct a vault; the inherent KeyVault::new constructor is intentionally not provided so that future required configuration cannot be silently bypassed.

Implementations§

Source §

impl KeyVaultBuilder

Source

pub fn new() -> Self

Start a new builder with default configuration and a default-range StandardFragmenter.

Source

pub fn normalize_with_blake3(self, enabled: bool) -> Self

Enable or disable BLAKE3 normalization of input key material.

Default: true. Disabling normalization preserves the original byte pattern of the key in storage, which can leak format cues (DER envelopes, PEM markers, ASCII-armored data). Disable only when you have a specific reason to preserve the original bytes.

Source

pub fn with_chunk_range(self, min: usize, max: usize) -> Self

Customize the fragmenter chunk-size range.

Defaults are documented on StandardFragmenter::new. min is clamped to >= 1 and max to >= min. Calling this replaces any previously-configured chunk range and resets the decoy strategy to None; configure decoy after this call.

Source

pub fn with_codex<C>(self, codex: C) -> Self
where C: Codex + 'static,

Attach a Layer-5 codex to the vault.

When set, every byte of the (optionally BLAKE3-normalized) key passes through codex.encode() before being handed to the fragmenter; defragment applies codex.decode() to recover the original bytes. For involution-based codices (StaticCodex, DynamicCodex, involution closures wrapped in FnCodex) decode == encode, but the vault calls them by name so non-involution codices would also work in principle.

The codex is held in an Arc<dyn Codex> so the same codex can be shared across multiple vaults (rarely useful — usually each vault wants its own DynamicCodex).

§Examples

use key_vault::{DynamicCodex, KeyVaultBuilder};

let vault = KeyVaultBuilder::new()
    .with_codex(DynamicCodex::new().unwrap())
    .build();
// The vault now applies the codex transformation transparently
// on every fragment / defragment.

Source

pub fn with_decoy<D>(self, decoy: D) -> Self
where D: DecoyStrategy + 'static,

Attach a Layer-4 decoy strategy to the underlying fragmenter.

When set, every KeyVault::fragment call also produces decoy chunks from the strategy. Decoys are interleaved with real chunks via the same Fisher-Yates shuffle and are skipped by defragment. See StandardFragmenter::with_decoy for details on chunk-count and size selection.

Use SelfReferenceDecoy for the strongest statistical indistinguishability (recommended default); KeyDerivedDecoy for BLAKE3-XOF–derived CSPRNG-like output; RandomDecoy for raw CSPRNG output.

Source

pub fn with_monitor<M>(self, monitor: M) -> Self
where M: SecurityMonitor + 'static,

Attach a Layer-8 security monitor.

Replaces any previously-configured monitor. The monitor receives every event the vault produces — failure callbacks via KeyVault::report_failure, anomaly callbacks via KeyVault::report_anomalous_access, and threshold-breach callbacks when the failure tracker fires.

Default is NoMonitor — events go nowhere but threshold-driven lockout still works (lockout state is owned by the vault, not the monitor).

Source

pub fn with_failure_threshold(self, max: u32, window: Duration) -> Self

Configure the failure-threshold detector.

When KeyVault::report_failure records max failures for the same key_name within window, the vault transitions to lock-out state and the monitor’s on_threshold_breach fires.

Pass max = 0 to disable threshold lockout (the default). The vault will still forward every failure to the monitor; it just won’t lock out on its own.

window is the sliding-window size for the per-key failure counter; failures older than this fall off and no longer count.

Source

pub fn with_audit_sink<A>(self, sink: A) -> Self
where A: AuditSink + 'static,

Attach a Layer-9 audit sink.

Every vault operation (register, unregister, read, rotate, fragment, defragment, master-unlock attempt) emits an AuditEvent through this sink. Default is NoAudit — events are constructed and discarded.

See AuditSink for the implementor contract (non-blocking, no panics, no back-pressure).

Source

pub fn with_master_key(self, master: RawKey) -> Self

Register a master credential for emergency unlock.

The vault stores the BLAKE3 hash of the supplied bytes; the plaintext is dropped immediately (and zeroed via RawKey::Drop). Use KeyVault::unlock_with_master later to clear a threshold-driven lockout.

Calling this twice replaces the previously-stored hash. Pass an empty key (zero-length) to register a meaningless “match anything” credential — strongly discouraged; the function does not reject it for symmetry with the rest of the builder API.

Source