redoubt_zero_core/
lib.rs

1// Copyright (c) 2025-2026 Federico Hoerth <memparanoid@gmail.com>
2// SPDX-License-Identifier: GPL-3.0-only
3// See LICENSE in the repository root for full license text.
4
5//! # RedoubtZero-core
6//!
7//! RAII guards and systematic zeroization primitives for protecting sensitive data in memory.
8//!
9//! `RedoubtZero-core` provides composable building blocks for secure memory handling:
10//!
11//! - **[`ZeroizeOnDropSentinel`]**: Runtime verification that zeroization happened before drop
12//! - **[`ZeroizingMutGuard`]**: RAII guard for mutable references (auto-zeroizes on drop)
13//! - **Traits**: [`FastZeroizable`], [`ZeroizationProbe`], [`AssertZeroizeOnDrop`], [`MutGuarded`]
14//! - **Derive macro**: `#[derive(RedoubtZero)]` for automatic trait implementations
15//!
16//! ## Design Principles
17//!
18//! 1. **Systematic zeroization**: Guards auto-zeroize on drop (impossible to forget)
19//! 2. **Runtime verification**: [`ZeroizeOnDropSentinel`] ensures zeroization happened
20//! 3. **API safety**: High-level wrappers can prevent direct access to sensitive data
21//! 4. **Composability**: Traits work with collections, nested types, custom structs
22//!
23//! ## Quick Start
24//!
25//! ### Using `ZeroizingMutGuard`
26//!
27//! ```rust
28//! use redoubt_zero_core::{ZeroizingMutGuard, ZeroizationProbe};
29//!
30//! let mut sensitive: u64 = 12345;
31//!
32//! {
33//!     // Guard zeroizes `sensitive` when dropped
34//!     let mut guard = ZeroizingMutGuard::from(&mut sensitive);
35//!     *guard = 67890;
36//! } // guard drops here → sensitive is zeroized
37//!
38//! assert!(sensitive.is_zeroized());
39//! ```
40//!
41//! ### Manual Implementation
42//!
43//! ```rust
44//! use redoubt_zero_core::{ZeroizeOnDropSentinel, FastZeroizable, ZeroizationProbe, AssertZeroizeOnDrop, collections};
45//!
46//! struct Credentials {
47//!     username: Vec<u8>,
48//!     password: Vec<u8>,
49//!     __sentinel: ZeroizeOnDropSentinel,
50//! }
51//!
52//! impl Drop for Credentials {
53//!     fn drop(&mut self) {
54//!         self.fast_zeroize();
55//!     }
56//! }
57//!
58//! impl FastZeroizable for Credentials {
59//!     fn fast_zeroize(&mut self) {
60//!         self.username.fast_zeroize();
61//!         self.password.fast_zeroize();
62//!         self.__sentinel.fast_zeroize();
63//!     }
64//! }
65//!
66//! impl ZeroizationProbe for Credentials {
67//!     fn is_zeroized(&self) -> bool {
68//!         let fields: [&dyn ZeroizationProbe; 2] = [
69//!             collections::to_zeroization_probe_dyn_ref(&self.username),
70//!             collections::to_zeroization_probe_dyn_ref(&self.password),
71//!         ];
72//!         collections::collection_zeroed(&mut fields.into_iter())
73//!     }
74//! }
75//!
76//! impl AssertZeroizeOnDrop for Credentials {
77//!     fn clone_sentinel(&self) -> ZeroizeOnDropSentinel {
78//!         self.__sentinel.clone()
79//!     }
80//!     fn assert_zeroize_on_drop(self) {
81//!         redoubt_zero_core::assert::assert_zeroize_on_drop(self);
82//!     }
83//! }
84//!
85//! let creds = Credentials {
86//!     username: b"admin".to_vec(),
87//!     password: b"secret".to_vec(),
88//!     __sentinel: ZeroizeOnDropSentinel::default(),
89//! };
90//!
91//! // Verify zeroization happens on drop
92//! creds.assert_zeroize_on_drop(); // ✅ Passes
93//! ```
94//!
95//! ## Safety
96//!
97//! This crate uses `#![warn(unsafe_op_in_unsafe_fn)]` and minimizes `unsafe` usage.
98//! All guards rely on RAII (Drop trait) for safety guarantees.
99//!
100//! ## License
101//!
102//! GPL-3.0-only
103//!
104#![cfg_attr(not(test), no_std)]
105#![warn(missing_docs)]
106#![warn(unsafe_op_in_unsafe_fn)]
107
108extern crate alloc;
109
110#[cfg(test)]
111mod tests;
112
113mod traits;
114/// Drop verification mechanism for ensuring zeroization happened before drop.
115///
116/// Contains [`ZeroizeOnDropSentinel`], the core type used to verify that `.zeroize()` was called.
117mod zeroize_on_drop_sentinel;
118mod zeroizing_guard;
119mod zeroizing_mut_guard;
120
121/// Trait implementations for raw pointers (`*mut T`, `*const T`).
122mod pointers;
123
124/// Trait implementations for Atomics
125mod atomics;
126
127/// Test helpers for verifying zeroization behavior in tests.
128///
129/// Primary export: [`assert_zeroize_on_drop()`](self::assert::assert_zeroize_on_drop).
130#[allow(clippy::module_name_repetitions)]
131pub mod assert;
132
133/// Trait implementations and helpers for collections (slices, arrays, `Vec<T>`).
134///
135/// Provides [`FastZeroizable`] and [`ZeroizationProbe`] implementations for standard collection types.
136pub mod collections;
137
138/// Wrapper types for primitive scalars with [`ZeroizeOnDropSentinel`] support.
139///
140/// Exports: `U8`, `U16`, `U32`, `U64`, `U128`, `USIZE` - each wraps the corresponding primitive type.
141pub mod primitives;
142
143pub use traits::{
144    AssertZeroizeOnDrop, FastZeroizable, FastZeroize, MutGuarded, StaticFastZeroizable,
145    ZeroizationProbe, ZeroizeMetadata,
146};
147pub use zeroize_on_drop_sentinel::ZeroizeOnDropSentinel;
148pub use zeroizing_guard::ZeroizingGuard;
149pub use zeroizing_mut_guard::ZeroizingMutGuard;
redoubt_zero_core/lib.rs

redoubt_zero_core/
lib.rs
