key_vault/
lib.rs

1//! # key-vault
2//!
3//! ENTERPRISE-GRADE KEY MANAGEMENT VAULT
4//!
5//! 9-layer defense-in-depth in-memory key storage. Fragmented across non-contiguous
6//! mlock'd allocations, interleaved with self-referential decoy bytes, optionally
7//! transformed through a codex layer, with constant-time operations, zero-on-drop,
8//! security monitoring, and audit logging.
9//!
10//! # The 9 Layers (plus bonus Layer 10)
11//!
12//! 1. **Secure Acquisition** ([`KeyFetch`] trait — TPM/HSM/Keychain/File/Env)
13//! 2. **Memory Page Locking** (`mlock` / `VirtualLock` — prevents swap)
14//! 3. **Fragment Strategy** ([`FragmentStrategy`] — variable chunks, shuffled, non-contiguous)
15//! 4. **Decoy Bytes** ([`DecoyStrategy`] — self-referential filler, statistically indistinguishable)
16//! 5. **Codex Transformation** ([`Codex`] — byte swap via involution)
17//! 6. **Constant-Time Operations** (`subtle::ConstantTimeEq`)
18//! 7. **Zero-On-Drop** (`zeroize` crate)
19//! 8. **Security Monitor** ([`SecurityMonitor`] — failed decrypt detection, threshold lockout)
20//! 9. **Audit Logging** (every key access tracked)
21//! 10. **(Bonus) Page Protection Toggling** (PROT_NONE when not in use)
22//!
23//! See `docs/SECURITY.md` for the full architecture and `docs/TRANSFORMATION.md`
24//! for a visual walkthrough.
25//!
26//! # Status
27//!
28//! Phase 0.2.0 — foundation types defined. [`KeyHandle`], [`KeyVault`],
29//! [`KeyVaultBuilder`], the five core traits, [`IdentityCodex`], and
30//! [`tee::detect_tee_capabilities`] are in place. Real fragmentation, mlock,
31//! decoy, and zeroize land in Phases 0.3 and 0.4. See `.dev/ROADMAP.md` for
32//! the full milestone plan.
33//!
34//! # License
35//!
36//! Dual-licensed under Apache-2.0 OR MIT.
37
38#![doc(html_root_url = "https://docs.rs/key-vault")]
39#![cfg_attr(docsrs, feature(doc_cfg))]
40#![cfg_attr(not(feature = "std"), no_std)]
41// REPS §Code Quality canonical lint set. `#![deny(warnings)]` is
42// intentionally NOT used at the crate root — new rustc versions can
43// introduce lints that retroactively break downstream builds of a
44// published crate. CI carries `RUSTFLAGS="-D warnings"` instead so the
45// gate is enforced where the lint surface is pinned to the toolchain
46// matrix.
47#![deny(missing_docs)]
48#![deny(unsafe_op_in_unsafe_fn)]
49#![deny(unused_must_use)]
50#![deny(unused_results)]
51#![deny(clippy::unwrap_used)]
52#![deny(clippy::expect_used)]
53#![deny(clippy::todo)]
54#![deny(clippy::unimplemented)]
55#![deny(clippy::unreachable)]
56#![deny(clippy::print_stdout)]
57#![deny(clippy::print_stderr)]
58#![deny(clippy::dbg_macro)]
59#![deny(clippy::undocumented_unsafe_blocks)]
60#![deny(clippy::missing_safety_doc)]
61#![warn(clippy::pedantic)]
62#![allow(clippy::module_name_repetitions)]
63
64extern crate alloc;
65
66pub mod audit;
67pub mod codex;
68pub mod decoy;
69mod error;
70pub mod fetcher;
71pub mod fragment;
72mod handle;
73mod memory;
74mod metadata;
75pub mod monitor;
76mod normalize;
77pub mod tee;
78mod vault;
79
80#[cfg(feature = "monitor-tracing")]
81pub use crate::audit::LogAudit;
82pub use crate::audit::{AccessKind, AuditEvent, AuditSink, NoAudit};
83pub use crate::codex::{Codex, DynamicCodex, IdentityCodex, StaticCodex};
84pub use crate::decoy::{DecoyStrategy, KeyDerivedDecoy, RandomDecoy, SelfReferenceDecoy};
85pub use crate::error::{Error, Result};
86#[cfg(feature = "fetcher-env")]
87pub use crate::fetcher::EnvFetch;
88#[cfg(feature = "fetcher-file")]
89pub use crate::fetcher::FileFetch;
90#[cfg(feature = "fetcher-keychain")]
91pub use crate::fetcher::KeychainFetch;
92#[cfg(feature = "fetcher-tpm")]
93pub use crate::fetcher::TpmFetch;
94pub use crate::fetcher::{FetchContext, KeyFetch, RawKey};
95pub use crate::fragment::{
96    FragmentStrategy, Fragments, InterleavedFragmenter, LayeredFragmenter, RandomFragmenter,
97    StandardFragmenter,
98};
99pub use crate::handle::{KeyHandle, KeyId};
100pub use crate::metadata::{AlgorithmHint, KeyMetadata};
101#[cfg(feature = "monitor-tracing")]
102pub use crate::monitor::LogMonitor;
103pub use crate::monitor::{
104    AccessContext, CompositeMonitor, FailureContext, NoMonitor, SecurityMonitor, ThresholdContext,
105};
106pub use crate::vault::{KeyVault, KeyVaultBuilder, VaultConfig};
107
108/// Crate version string, populated by Cargo at build time.
109pub const VERSION: &str = env!("CARGO_PKG_VERSION");
key_vault/lib.rs

key_vault/
lib.rs
