Struct SecretBox 

pub struct SecretBox<S: Zeroize> { /* private fields */ }

A pure-software, stack-native hardened wrapper for sensitive values (no_std compatible).

SecretBox protects inline data by surrounding it with dynamically generated, randomized canaries (verified via compiler-optimization-proof read_volatile checks) to immediately panic during stack smashing buffer overflows.

It implements mathematically strict &mut self concurrency locks, forces zeroization on drop, and mandates that data can only be touched inside strictly scoped .with_secret() closures to eliminate accidental memory leaks. It strictly forbids Clone to prevent key scattering.

Examples

use sec_mem::SecretBox;

// Wrap a basic 32-bit integer or a 256-bit array entirely on the stack
let mut secret = SecretBox::new([0x42u8; 32]);

// The data can only be accessed exclusively inside a closure
secret.with_secret_mut(|s| {
    s[0] = 0x99;
}); 
// Any stack corruption that occurred is detected here, panicking instantly.

Implementations

impl<S: Zeroize> SecretBox<S>

pub fn new(secret: S) -> Self

Create a secret value using an inline value.

pub fn with_secret<F, R>(&mut self, f: F) -> R

where F: FnOnce(&S) -> R,

Safer alternative: Provide an exclusive closure-based interface. Requires &mut self to mathematically prevent concurrent multi-threaded aliasing or reference sharing.

pub fn with_secret_mut<F, R>(&mut self, f: F) -> R

where F: FnOnce(&mut S) -> R,

Safer mutable alternative: Provide a closure-based interface.

impl<S: Zeroize + Default> SecretBox<S>

pub fn init_with_mut(ctr: impl FnOnce(&mut S)) -> Self

Create a secret value using a function that can initialize the value in-place.

impl<S: Zeroize> SecretBox<S>

pub fn constant_time_eq(&mut self, other: &mut Self) -> Choice

where S: ConstantTimeEq,

Performs a constant-time comparison of two SecretBoxes. Requires &mut on both to enforce exclusive access and check canaries.

Trait Implementations

impl<S: Zeroize> Debug for SecretBox<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S: Zeroize + Default> Default for SecretBox<S>

fn default() -> Self

Returns the “default value” for a type.

impl<S: Zeroize> Drop for SecretBox<S>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<S: Zeroize> From<S> for SecretBox<S>

fn from(source: S) -> Self

Converts to this type from the input type.

impl<S: Zeroize> Zeroize for SecretBox<S>

fn zeroize(&mut self)

Zero out this object from memory using Rust intrinsics which ensure the zeroization operation is not “optimized away” by the compiler.

impl<S: Zeroize> ZeroizeOnDrop for SecretBox<S>