sec_mem/lib.rs
1//! # SecMem
2//!
3//! A high-assurance, attack-resistant cryptographic memory allocator for Rust.
4//!
5//! Designed to aggressively protect sensitive data (cryptographic keys, passwords, PII)
6//! from OS-level exploits, memory dumping, buffer overflows, and side-channel attacks.
7//!
8//! ## Feature Flags
9//!
10//! | Feature | Description | Default |
11//! |---------|-------------|---------|
12//! | `sec_mem` | Enables `SecMem`, the OS-level memory hardening container. Requires `libc` and Linux. | **Yes** |
13//! | `encryption` | Enables ChaCha20/XOR-blinded encrypt-at-rest for `SecMem`. Stores the master key in `memfd_secret`. | **Yes** |
14//! | `key_shielding`| Enables OpenSSH-style 16 KiB pre-key `blake3` derivation to heavily defend against side-channels. | **No** |
15//!
16//! *(Note: `SecretBox` is always available and fully `no_std` compatible, regardless of features).*
17//!
18//! ## 1. Hardware-Accelerated OS Hardening (`SecMem`)
19//!
20//! Available with the `sec_mem` feature. Uses raw Linux syscalls to create hardware-isolated memory.
21//!
22//! * **XOR-Blinded Encrypt-at-Rest**: Memory is dynamically ChaCha20/XOR masked.
23//! * **Optional Key Shielding**: Defeats Spectre/Rowhammer using an optional 16 KiB XOR-split pre-key and dynamic `blake3` derivation (`key_shielding` feature).
24//! * **Intel MPK**: Grants zero-syscall hardware isolation using `pkey_mprotect` and `WRPKRU`.
25//! * **Memory Sealing**: Uses `mseal` to permanently lock guard pages and permissions.
26//! * **mlock & Anti-Tracing**: Forces `mlock`, `MADV_DONTDUMP`, `MADV_DONTFORK`, and `PR_SET_DUMPABLE(0)`.
27//!
28//! ```rust
29//! # #[cfg(feature = "sec_mem")]
30//! # {
31//! use sec_mem::SecMem;
32//!
33//! let mut secure_key = SecMem::new([0xAAu8; 32]);
34//! secure_key.access_mut(|key| {
35//! key[0] = 0xBB;
36//! }); // Hardware locks instantly engage on closure drop.
37//! # }
38//! ```
39//!
40//! ## 2. Software-Enforced Memory Hardening (`SecretBox`)
41//!
42//! A highly portable, stack-native, software-only wrapper requiring zero OS syscalls.
43//!
44//! * **Dynamic Volatile Canaries**: Generates randomized canaries at startup (`libc::getrandom` or `RDRAND`), verified via `core::ptr::read_volatile`.
45//! * **Strict Exclusive Access**: Enforces `&mut self` to mathematically eliminate concurrency race conditions.
46//! * **Closure-Restricted Lifetimes**: No `expose_secret()`. Uses strictly scoped injection closures (`.with_secret()`).
47//!
48//! ```rust
49//! use sec_mem::SecretBox;
50//!
51//! let mut portable_box = SecretBox::new(42u32);
52//! portable_box.with_secret(|val| {
53//! assert_eq!(*val, 42);
54//! }); // Stack canaries verified via volatile reads!
55//! ```
56
57#![cfg_attr(not(feature = "sec_mem"), no_std)]
58#![cfg_attr(docsrs, feature(doc_cfg))]
59#![warn(missing_debug_implementations, missing_docs, rust_2018_idioms)]
60
61#[cfg(feature = "sec_mem")]
62mod sec_mem;
63mod secret_box;
64
65#[cfg(feature = "sec_mem")]
66pub use sec_mem::{SecMem, SecretAccess, harden_process};
67pub use secret_box::SecretBox;
68pub use zeroize;