Struct Dynamic 

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

Re-export of the Dynamic type. 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, ExposeSecret};
let secret: Dynamic<String> = "hunter2".into();
assert_eq!(secret.expose_secret(), "hunter2");

With already-boxed values:

use secure_gate::{Dynamic, ExposeSecret};
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, ExposeSecret, ExposeSecretMut};
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.

impl Dynamic<String>

This impl block contains no items.

Ergonomic helpers for common heap types

impl Dynamic<String>

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

Constant-time equality comparison.

Compares the byte contents of two Dynamic<String> instances in constant time to prevent timing attacks. The strings are compared as UTF-8 byte sequences.

Examples

use secure_gate::Dynamic;
let a: Dynamic<String> = Dynamic::new("secret".to_string());
let b: Dynamic<String> = Dynamic::new("secret".to_string());
assert!(a.ct_eq(&b));

impl Dynamic<Vec<u8>>

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

Constant-time equality comparison.

Compares the byte contents of two Dynamic<Vec<u8>> instances in constant time to prevent timing attacks. The vectors are compared as byte slices.

Examples

use secure_gate::Dynamic;
let a: Dynamic<Vec<u8>> = Dynamic::new(vec![1, 2, 3]);
let b: Dynamic<Vec<u8>> = Dynamic::new(vec![1, 2, 3]);
assert!(a.ct_eq(&b));

impl Dynamic<Vec<u8>>

Random generation — only available with rand feature.

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 DynamicRandom. Equivalent to: DynamicRandom::generate(len).into_inner()

Example

use secure_gate::{Dynamic, ExposeSecret};
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 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 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: CloneSafe> Clone for Dynamic<T>

Available on crate feature zeroize only.

Opt-in Clone — only for types marked CloneSafe.

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>

Debug implementation (always redacted).

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

Formats the value using the given formatter.

impl ExposeSecret for Dynamic<CloneableStringInner>

Available on crate feature zeroize only.

Implementation for Dynamic<CloneableStringInner> - exposes the inner wrapper.

type Inner = CloneableStringInner

The inner secret type being exposed.

fn expose_secret(&self) -> &CloneableStringInner

Expose the secret for read-only access.

fn len(&self) -> usize

Returns the length of the secret.

fn is_empty(&self) -> bool

Returns true if the secret is empty.

impl ExposeSecret for Dynamic<CloneableVecInner>

Available on crate feature zeroize only.

Implementation for Dynamic<CloneableVecInner> - exposes the inner wrapper.

type Inner = CloneableVecInner

The inner secret type being exposed.

fn expose_secret(&self) -> &CloneableVecInner

Expose the secret for read-only access.

fn len(&self) -> usize

Returns the length of the secret.

fn is_empty(&self) -> bool

Returns true if the secret is empty.

impl ExposeSecret for Dynamic<String>

Implementation for Dynamic<String> - provides full read/write access.

Dynamic<String> is a core wrapper that allows both reading and mutation of secrets. This implementation directly accesses the inner field.

type Inner = String

The inner secret type being exposed.

fn expose_secret(&self) -> &String

Expose the secret for read-only access.

fn len(&self) -> usize

Returns the length of the secret.

fn is_empty(&self) -> bool

Returns true if the secret is empty.

impl<T> ExposeSecret for Dynamic<Vec<T>>

Implementation for Dynamic<Vec<T>> - provides full read/write access.

Dynamic<Vec<T>> is a core wrapper that allows both reading and mutation of secrets. This implementation directly accesses the inner field.

type Inner = Vec<T>

The inner secret type being exposed.

fn expose_secret(&self) -> &Vec<T>

Expose the secret for read-only access.

fn len(&self) -> usize

Returns the length of the secret.

fn is_empty(&self) -> bool

Returns true if the secret is empty.

impl ExposeSecretMut for Dynamic<CloneableStringInner>

Available on crate feature zeroize only.

Implementation for Dynamic<CloneableStringInner> - provides mutable access.

fn expose_secret_mut(&mut self) -> &mut CloneableStringInner

Expose the secret for mutable access.

impl ExposeSecretMut for Dynamic<CloneableVecInner>

Available on crate feature zeroize only.

Implementation for Dynamic<CloneableVecInner> - provides mutable access.

fn expose_secret_mut(&mut self) -> &mut CloneableVecInner

Expose the secret for mutable access.

impl ExposeSecretMut for Dynamic<String>

Implementation for Dynamic<String> - provides mutable access.

Extends the read-only implementation with mutation capabilities.

fn expose_secret_mut(&mut self) -> &mut String

Expose the secret for mutable access.

impl<T> ExposeSecretMut for Dynamic<Vec<T>>

Implementation for Dynamic<Vec<T>> - provides mutable access.

Extends the read-only implementation with mutation capabilities.

fn expose_secret_mut(&mut self) -> &mut Vec<T>

Expose the secret for mutable access.

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

Additional conversions

Wrap a byte slice into a Dynamic Vec<u8>.

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

Converts to this type from the input type.

impl From<&str> for Dynamic<String>

Wrap a string slice in a Dynamic String.

fn from(s: &str) -> Self

Converts to this type from the input type.

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

Wrap a boxed value in a Dynamic secret.

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

Converts to this type from the input type.

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

fn from(rng: DynamicRandom) -> Self

Convert a DynamicRandom to Dynamic, transferring ownership.

This preserves all security guarantees. The DynamicRandom 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::DynamicRandom};
let random: Dynamic<Vec<u8>> = DynamicRandom::generate(64).into();

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

Convenient From impls

Wrap a value in a Dynamic secret by boxing it.

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.

Zeroize integration.

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.

Zeroize on drop integration.