Struct Dynamic

Source

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

Expand description

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;
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§

Source §

impl<T: ?Sized> Dynamic<T>

Source

pub fn new(value: U) -> Self
where U: Into<Box<T>>,

Wrap a value by boxing it.

Uses Into<Box<T>> for flexibility.

Source

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.

Source

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.

Source §

impl Dynamic<String>

§Ergonomic helpers for common heap types

Source

pub const fn len(&self) -> usize

Returns the length of the string in bytes.

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

Source

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.

Source §

impl<T> Dynamic<Vec<T>>

Source

pub const fn len(&self) -> usize

Returns the number of elements in the vector.

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

Source

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.

Source §

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

Constant-time equality for byte-convertible types — available with ct-eq feature.

Source

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

Constant-time equality comparison.

This is the only safe way to compare two dynamic secrets. Available only when the ct-eq feature is enabled.

§Example

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

Source §

impl Dynamic<CloneableStringInner>

Source

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.

Source

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.

Source

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

Source

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.

Source §

impl Dynamic<CloneableVecInner>

Source

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.

Source

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.

Source

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

Source

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.