Struct Dynamic 

pub struct Dynamic<T: ?Sized>(/* private fields */);

Heap-allocated secure secret wrapper.

This is a thin wrapper around Box<T> with enforced explicit exposure. Suitable for dynamic-sized secrets like String or Vec<u8>.

Security invariants:

• No Deref or AsRef — prevents silent access.
• Debug is always redacted.
• With zeroize, wipes the entire allocation on drop (including spare capacity).

Examples

Basic usage:

use secure_gate::Dynamic;
let secret: Dynamic<String> = "hunter2".into();
assert_eq!(secret.expose_secret(), "hunter2");

Mutable access:

use secure_gate::Dynamic;
let mut secret = Dynamic::<String>::new("pass".to_string());
secret.expose_secret_mut().push('!');
assert_eq!(secret.expose_secret(), "pass!");

With zeroize (automatic wipe):

use secure_gate::Dynamic;
let secret = Dynamic::<Vec<u8>>::new(vec![1u8; 32]);
drop(secret); // heap wiped automatically

Implementations

impl<T: ?Sized> Dynamic<T>

pub fn new_boxed(value: Box<T>) -> Self

Wrap an already-boxed value.

Zero-cost — just wraps the Box.

pub fn new<U>(value: U) -> Self

where U: Into<Box<T>>,

Wrap a value by boxing it.

Uses Into<Box<T>> for flexibility.

pub const fn expose_secret(&self) -> &T

Expose the inner value for read-only access.

This is the only way to read the secret — loud and auditable.

pub fn expose_secret_mut(&mut self) -> &mut T

Expose the inner value for mutable access.

This is the only way to mutate the secret — loud and auditable.

impl Dynamic<String>

pub const fn len(&self) -> usize

Returns the length of the string in bytes.

This is safe public metadata — does not expose the secret.

pub const fn is_empty(&self) -> bool

Returns true if the string is empty (zero bytes).

This is safe public metadata — does not expose the secret.

impl<T> Dynamic<Vec<T>>

pub const fn len(&self) -> usize

Returns the number of elements in the vector.

This is safe public metadata — does not expose the secret.

pub const fn is_empty(&self) -> bool

Returns true if the vector is empty (zero elements).

This is safe public metadata — does not expose the secret.

impl<T> Dynamic<T>

where T: ?Sized + AsRef<[u8]>,

pub fn ct_eq(&self, other: &Self) -> bool

impl Dynamic<Vec<u8>>

pub fn generate_random(len: usize) -> Self

Generate fresh random bytes of the specified length using the OS RNG.

This is a convenience method that generates random bytes directly without going through DynamicRng. Equivalent to: DynamicRng::generate(len).into_inner()

Example

use secure_gate::Dynamic;
let random: Dynamic<Vec<u8>> = Dynamic::generate_random(64);
assert_eq!(random.len(), 64);

pub fn try_generate_random(len: usize) -> Result<Self, OsError>

Try to generate random bytes for Dynamic.

Returns an error if the RNG fails.

Example

use secure_gate::Dynamic;
let random: Result<Dynamic<Vec<u8>>, rand::rand_core::OsError> = Dynamic::try_generate_random(64);
assert!(random.is_ok());

impl Dynamic<CloneableStringInner>

pub const fn expose_inner(&self) -> &String

pub fn expose_inner_mut(&mut self) -> &mut String

pub fn init_with<F>(constructor: F) -> Self

where F: FnOnce() -> String,

Construct a cloneable string secret by building it in a closure.

This minimizes the time the secret spends on the stack:

• The closure builds a temporary String.
• It is immediately cloned to the heap.
• The temporary is zeroized before returning.

Use this when reading passwords or tokens from user input.

Example

use secure_gate::CloneableString;
use std::io::{self, Write};

fn read_password() -> io::Result<String> {
    let mut input = String::new();
    io::stdout().flush()?;
    io::stdin().read_line(&mut input)?;
    Ok(input.trim_end().to_string())
}

let pw = CloneableString::init_with(|| read_password().unwrap());

pub fn try_init_with<F, E>(constructor: F) -> Result<Self, E>

where F: FnOnce() -> Result<String, E>,

Fallible version of init_with.

Useful when construction can fail (e.g., I/O errors).

impl Dynamic<CloneableVecInner>

pub const fn expose_inner(&self) -> &Vec<u8>

pub fn expose_inner_mut(&mut self) -> &mut Vec<u8>

pub fn init_with<F>(constructor: F) -> Self

where F: FnOnce() -> Vec<u8>,

Construct a cloneable vec secret by building it in a closure.

Same stack-minimization benefits as CloneableString::init_with.

Example

use secure_gate::CloneableVec;

let seed = CloneableVec::init_with(|| {
    let mut v = vec![0u8; 32];
    // Fill from some source...
    v
});

pub fn try_init_with<F, E>(constructor: F) -> Result<Self, E>

where F: FnOnce() -> Result<Vec<u8>, E>,

Fallible version of init_with.

Trait Implementations

impl<T: CloneableSecretMarker> Clone for Dynamic<T>

Available on crate feature zeroize only.

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: ?Sized> Debug for Dynamic<T>

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

Formats the value using the given formatter.

impl From<&[u8]> for Dynamic<Vec<u8>>

fn from(slice: &[u8]) -> Self

Converts to this type from the input type.

impl From<&str> for Dynamic<String>

fn from(s: &str) -> Self

Converts to this type from the input type.

impl<T: ?Sized> From<Box<T>> for Dynamic<T>

fn from(boxed: Box<T>) -> Self

Converts to this type from the input type.

impl From<DynamicRng> for Dynamic<Vec<u8>>

fn from(rng: DynamicRng) -> Self

Convert a DynamicRng to Dynamic, transferring ownership.

This preserves all security guarantees. The DynamicRng type ensures the value came from secure RNG, and this conversion transfers that value to Dynamic without exposing bytes.

Example

use secure_gate::{Dynamic, random::DynamicRng};
let random: Dynamic<Vec<u8>> = DynamicRng::generate(64).into();

impl<T> From<T> for Dynamic<T>

fn from(value: T) -> Self

Converts to this type from the input type.

impl<T: ?Sized + Zeroize> Zeroize for Dynamic<T>

Available on crate feature zeroize only.

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<T: ?Sized + Zeroize> ZeroizeOnDrop for Dynamic<T>

Available on crate feature zeroize only.