key-vault 1.0.0

Enterprise-grade key management vault for Rust. 9-layer defense-in-depth: fragmentation, decoy bytes, codex transform, mlock + zeroize, constant-time ops, security monitoring. Pluggable key fetchers (TPM, keychain, file, env). Sub-microsecond access. REPS-compliant.
Documentation

9-Layer Defense Architecture

The complete defense stack:

Layer Defense Defends Against
1 Secure Acquisition (TPM, Keychain, etc.) Untrusted key sources
2 Memory Page Locking (mlock / VirtualLock) Swap files, hibernation
3 Fragment Strategy (variable chunks, shuffle) Pattern recognition, memory scraping
4 Decoy Bytes (self-referential filler) Entropy/frequency analysis
5 Codex Transformation (byte swap) Memory dump analysis
6 Constant-Time Operations Timing side-channels
7 Zero-On-Drop Use-after-free leakage
8 Security Monitor (failure detection) Brute-force, anomalous access
9 Audit Logging Forensic trail, compliance
10 (Bonus) Page Protection Toggling Snapshot attacks

Full details: see docs/SECURITY.md for the comprehensive security architecture.

Visual walkthrough: see docs/TRANSFORMATION.md for a step-by-step trace of what happens to a key as it passes through all the layers.

Performance targets (1.0 design — verified in 0.10.0)

Measured numbers from the reference machine (see docs/PERFORMANCE.md for methodology and the full result tables):

Target Measured Status
Vault construction (empty) ~165 ns ✅
with_key defrag, no codex, 16/32/64/256 B 31 / 39 / 51 / 147 ns ✅ all under 500 ns
with_key defrag, with codex, 16/32/64/256 B 48 / 72 / 126 / 439 ns ✅ all under 1 µs
Concurrent reads, 1 → 64 threads scales out, no contention ✅ lock-free
Memory overhead per key (Linux 1000-key RSS) ~5 KiB ✅ under 16 KiB
Allocations per with_key (default NoAudit) 0 (dhat-measured over 100k iterations) ✅ zero-alloc hot path

Run cargo bench --all-features to reproduce on your hardware.

Quick start

[dependencies]
key-vault = "1.0"

use key_vault::{DynamicCodex, KeyVaultBuilder, RawKey, SelfReferenceDecoy};
use key_vault::tee::detect_tee_capabilities;

// Build a vault with the full default stack: Layer 2 (mlock/VirtualLock)
// + Layer 3 (StandardFragmenter) + Layer 4 (SelfReferenceDecoy — the
// strongest decoy) + Layer 5 (per-vault DynamicCodex involution)
// + Layer 6 (ConstantTimeEq) + Layer 7 (zero-on-drop).
let vault = KeyVaultBuilder::new()
    .normalize_with_blake3(true) // default
    .with_codex(DynamicCodex::new().expect("codex"))
    .with_decoy(SelfReferenceDecoy)
    .build();

// Hand the vault some key material and get back an opaque, scattered,
// mlock'd, zeroed-on-drop representation with decoy chunks mixed in.
let raw = RawKey::new(b"my application key".to_vec());
let frags = vault.fragment(&raw).expect("fragment");

// Reassemble when you need to use it. With BLAKE3 normalization on,
// the recovered bytes are the 32-byte hash of the input.
let recovered = vault.defragment(&frags).expect("defragment");
assert_eq!(recovered.len(), 32);

// Snapshot the host's TEE capabilities at startup:
let caps = detect_tee_capabilities();
println!("{caps}");

Threat model

key-vault is designed to defend against:

  • Memory scraping by attackers with read access — malware, forensic tools
  • Forensic memory analysis — swap files, hibernation files, crash dumps
  • Statistical pattern recognition — entropy analysis, frequency analysis
  • Use-after-free leakage — keys persisting after they should have been wiped
  • Brute-force decryption attempts — failed attempts trigger alerts
  • Timing side-channels — constant-time operations
  • Insider threats / forensic compliance — full audit trail

It does NOT defend against:

  • Code execution within your process — an attacker who can call your reassembly logic
  • Hardware-level memory access (DMA attacks) — use IOMMU + hardware mitigations
  • Cold-boot attacks — use full disk encryption + power-down protocol
  • Side-channel attacks on cryptographic operations — that's crypt-io's job
  • Quantum computer attacks on asymmetric crypto — use post-quantum algorithms (symmetric defaults are PQ-safe)

See docs/SECURITY.md for the full threat model.

Documentation

Standards

  • REPS (Rust Efficiency & Performance Standards) governs every decision. See REPS.md.
  • MSRV: Rust 1.85.
  • Edition: 2024.
  • Cross-platform: Linux, macOS, Windows.

License

Dual-licensed under either of:

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.