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");

With already-boxed values:

use secure_gate::Dynamic;
let boxed_secret = Box::new("hunter2".to_string());
let secret: Dynamic<String> = boxed_secret.into(); // or Dynamic::from(boxed_secret)
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<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

Returns a reference to the inner string without cloning.

This method provides direct access to the wrapped String. The reference is valid for the lifetime of the CloneableString.

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

Returns a mutable reference to the inner string.

This method provides direct mutable access to the wrapped String. Use this when you need to modify the string contents in-place.

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.

Same stack-minimization benefits as init_with, but allows for construction that may fail with an error. Useful when reading secrets from fallible sources like files, network connections, or user input that may encounter I/O errors.

impl Dynamic<CloneableVecInner>

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

Returns a reference to the inner vector without cloning.

This method provides direct access to the wrapped Vec<u8>. The reference is valid for the lifetime of the CloneableVec.

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

Returns a mutable reference to the inner vector.

This method provides direct mutable access to the wrapped Vec<u8>. Use this when you need to modify the vector contents in-place.

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.

Same stack-minimization benefits as init_with, but allows for construction that may fail with an error. Useful when reading secrets from fallible sources like files or network connections.

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.