Struct Dynamic 

pub struct Dynamic<T: ?Sized + Zeroize> { /* private fields */ }

Heap-allocated secret wrapper with explicit access and automatic zeroization on drop.

Variable-length secrets (passwords, API keys, ciphertexts). Inner type must implement Zeroize. Secret bytes live on the heap only — never on the stack. Requires alloc.

See Fixed<T> for the stack-allocated alternative.

use secure_gate::{Dynamic, RevealSecret};

let pw: Dynamic<String> = Dynamic::new(String::from("hunter2"));
assert_eq!(pw.with_secret(|s: &String| s.len()), 7);
assert_eq!(format!("{:?}", pw), "[REDACTED]");

Zero-cost heap-allocated wrapper for variable-length secrets.

Dynamic<T> stores a T: Zeroize value in a Box<T> and unconditionally zeroizes it on drop (including Vec/String spare capacity). There is no Deref, AsRef, or Copy — every access is explicit through RevealSecret or RevealSecretMut.

This is not Fixed<T> — it is the heap-allocated alternative for variable-length secrets. Secret bytes never reside on the stack.

Examples

use secure_gate::{Dynamic, RevealSecret};

let pw: Dynamic<String> = Dynamic::new(String::from("hunter2"));
assert_eq!(pw.with_secret(|s: &String| s.len()), 7);
assert_eq!(format!("{:?}", pw), "[REDACTED]");

Constructors for Dynamic<Vec<u8>>

Constructor	Feature	Notes
new(value)	—	Accepts Vec<u8>, &[u8], Box<Vec<u8>>
new_with(f)	—	Scoped closure construction
try_from_hex(s)	encoding-hex	Constant-time hex decoding
try_from_base64url(s)	encoding-base64	Constant-time Base64url decoding
try_from_bech32(s, hrp)	encoding-bech32	HRP-validated Bech32
try_from_bech32_unchecked(s)	encoding-bech32	Bech32 without HRP check
try_from_bech32m(s, hrp)	encoding-bech32m	HRP-validated Bech32m
try_from_bech32m_unchecked(s)	encoding-bech32m	Bech32m without HRP check
from_random(len)	rand	System RNG
from_rng(len, rng)	rand	Custom RNG

See also

• RevealSecret / RevealSecretMut — the 3-tier access traits.
• Fixed<T> — stack-allocated alternative.

Implementations

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

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

where U: Into<Box<T>>,

Wraps value in a Box<T> and returns a Dynamic<T>.

Accepts any type that implements Into<Box<T>> — including owned values, Box<T>, String, Vec<u8>, &str (via the blanket From<&str> impl), etc.

Equivalent to Dynamic::from(value) — #[doc(alias = "from")] is set so both names appear in docs.rs search.

Requires the alloc feature (which Dynamic<T> itself always requires).

impl Dynamic<Vec<u8>>

pub fn to_hex(&self) -> String

Encodes the secret bytes as a lowercase hex string.

pub fn to_hex_upper(&self) -> String

Encodes the secret bytes as an uppercase hex string.

pub fn to_hex_zeroizing(&self) -> EncodedSecret

Encodes the secret bytes as a lowercase hex string, returning EncodedSecret to preserve zeroization.

pub fn to_hex_upper_zeroizing(&self) -> EncodedSecret

Encodes the secret bytes as an uppercase hex string, returning EncodedSecret to preserve zeroization.

pub fn try_from_hex(s: &str) -> Result<Self, HexError>

Decodes a hex string (lowercase, uppercase, or mixed) into Dynamic<Vec<u8>>.

The decoded buffer is kept inside a Zeroizing wrapper until after the Box allocation completes, guaranteeing zeroization even on OOM panic.

impl Dynamic<Vec<u8>>

pub fn to_base64url(&self) -> String

Encodes the secret bytes as an unpadded Base64url string (RFC 4648, URL-safe alphabet).

pub fn to_base64url_zeroizing(&self) -> EncodedSecret

Encodes the secret bytes as an unpadded Base64url string, returning EncodedSecret to preserve zeroization.

pub fn try_from_base64url(s: &str) -> Result<Self, Base64Error>

Decodes a Base64url (unpadded) string into Dynamic<Vec<u8>>.

The decoded buffer is kept inside a Zeroizing wrapper until after the Box allocation completes, guaranteeing zeroization even on OOM panic.

impl Dynamic<Vec<u8>>

pub fn try_to_bech32(&self, hrp: &str) -> Result<String, Bech32Error>

Encodes the secret bytes as a Bech32 (BIP-173) string with the given HRP.

pub fn try_to_bech32_zeroizing( &self, hrp: &str, ) -> Result<EncodedSecret, Bech32Error>

Encodes the secret bytes as a Bech32 string, returning EncodedSecret to preserve zeroization.

pub fn try_from_bech32(s: &str, expected_hrp: &str) -> Result<Self, Bech32Error>

Decodes a Bech32 (BIP-173) string into Dynamic<Vec<u8>>, validating the HRP (case-insensitive).

The decoded buffer is kept inside a Zeroizing wrapper until after the Box allocation completes, guaranteeing zeroization even on OOM panic.

HRP comparison is non-constant-time — this is intentional, as the HRP is public metadata, not secret material.

pub fn try_from_bech32_unchecked(s: &str) -> Result<Self, Bech32Error>

Decodes a Bech32 (BIP-173) string into Dynamic<Vec<u8>> without validating the HRP.

Use try_from_bech32 in security-critical code to prevent cross-protocol confusion attacks.

impl Dynamic<Vec<u8>>

pub fn try_to_bech32m(&self, hrp: &str) -> Result<String, Bech32Error>

Encodes the secret bytes as a Bech32m (BIP-350) string with the given HRP.

pub fn try_to_bech32m_zeroizing( &self, hrp: &str, ) -> Result<EncodedSecret, Bech32Error>

Encodes the secret bytes as a Bech32m string, returning EncodedSecret to preserve zeroization.

pub fn try_from_bech32m( s: &str, expected_hrp: &str, ) -> Result<Self, Bech32Error>

Decodes a Bech32m (BIP-350) string into Dynamic<Vec<u8>>, validating the HRP (case-insensitive).

The decoded buffer is kept inside a Zeroizing wrapper until after the Box allocation completes, guaranteeing zeroization even on OOM panic.

pub fn try_from_bech32m_unchecked(s: &str) -> Result<Self, Bech32Error>

Decodes a Bech32m (BIP-350) string into Dynamic<Vec<u8>> without validating the HRP.

Use try_from_bech32m in security-critical code.

impl Dynamic<Vec<u8>>

Construction helpers and random generation for Dynamic<Vec<u8>>.

pub fn new_with<F>(f: F) -> Self

where F: FnOnce(&mut Vec<u8>),

Closure-based constructor for consistent API with Fixed::new_with. The actual secret data is allocated on the heap; this method exists for consistent security-first construction idiom across the crate.

impl Dynamic<String>

pub fn new_with<F>(f: F) -> Self

where F: FnOnce(&mut String),

Closure-based constructor for consistent API with Fixed::new_with. The actual secret data is allocated on the heap; this method exists for consistent security-first construction idiom across the crate.

impl Dynamic<Vec<u8>>

pub fn from_random(len: usize) -> Self

Fills a new Vec<u8> with len cryptographically secure random bytes and wraps it.

Uses the system RNG (SysRng). Requires the rand feature (and alloc, which Dynamic<Vec<u8>> always needs).

Panics

Panics if the system RNG fails to provide bytes (TryRng::try_fill_bytes returns Err). This is treated as a fatal environment error.

Examples

use secure_gate::{Dynamic, RevealSecret};

let nonce: Dynamic<Vec<u8>> = Dynamic::from_random(24);
assert_eq!(nonce.len(), 24);

pub fn from_rng<R: TryRng + TryCryptoRng>( len: usize, rng: &mut R, ) -> Result<Self, R::Error>

Allocates a Vec<u8> of length len, fills it from rng, and wraps it.

Accepts any TryCryptoRng + TryRng — for example, a seeded StdRng for deterministic tests. Requires the rand feature and alloc (implicit — Dynamic<T> itself requires it).

Errors

Returns R::Error if try_fill_bytes fails.

Examples

use rand::rngs::StdRng;
use rand::SeedableRng;
use secure_gate::Dynamic;

let mut rng = StdRng::from_seed([9u8; 32]);
let nonce: Dynamic<Vec<u8>> = Dynamic::from_rng(24, &mut rng).expect("rng fill");

impl Dynamic<Vec<u8>>

pub fn as_reader(&self) -> DynamicReader<'_>

Returns a DynamicReader that implements std::io::Read.

This replaces the common with_secret + Cursor boilerplate:

use std::io;
use secure_gate::Dynamic;

let secret = Dynamic::<Vec<u8>>::new(vec![1, 2, 3, 4]);

// Before: awkward closure + Cursor dance
// secret.with_secret(|b| io::copy(&mut Cursor::new(b), &mut encryptor))?;

// After: pipe directly into an encrypted writer — no intermediate buffer
let mut encryptor = io::sink(); // stand-in for a real encryptor
io::copy(&mut secret.as_reader(), &mut encryptor).unwrap();

Security

Each read() call copies secret bytes into the caller’s buffer. Prefer piping directly into encrypted writers rather than reading into intermediate buffers. The caller is responsible for zeroizing any destination buffer.

impl Dynamic<Vec<u8>>

pub fn deserialize_with_limit<'de, D>( deserializer: D, limit: usize, ) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserializes into Dynamic<Vec<u8>>, rejecting payloads larger than limit bytes.

The standard serde::Deserialize impl calls this with MAX_DESERIALIZE_BYTES. Use this method directly when you need a tighter or looser ceiling.

The intermediate buffer is kept inside a Zeroizing wrapper until after the Box allocation completes, guaranteeing zeroization even on OOM panic. Oversized buffers are also zeroized before the error is returned.

Important: this limit is enforced after the upstream deserializer has fully materialized the payload. It is a result-length acceptance bound, not a pre-allocation DoS guard. For untrusted input, enforce size limits at the transport or parser layer upstream.

impl Dynamic<String>

pub fn deserialize_with_limit<'de, D>( deserializer: D, limit: usize, ) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserializes into Dynamic<String>, rejecting payloads larger than limit bytes.

The standard serde::Deserialize impl calls this with MAX_DESERIALIZE_BYTES. Use this method directly when you need a tighter or looser ceiling.

The intermediate buffer is kept inside a Zeroizing wrapper until after the Box allocation completes, guaranteeing zeroization even on OOM panic. Oversized buffers are also zeroized before the error is returned.

Important: this limit is enforced after the upstream deserializer has fully materialized the payload. It is a result-length acceptance bound, not a pre-allocation DoS guard. For untrusted input, enforce size limits at the transport or parser layer upstream.

Trait Implementations

impl<T: Zeroize + CloneableSecret> Clone for Dynamic<T>

Available on crate feature cloneable only.

Opt-in cloning — requires cloneable feature and CloneableSecret marker. Each clone is independently zeroized on drop, but cloning increases exposure surface.

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> ConstantTimeEq for Dynamic<T>

where T: ConstantTimeEq + ?Sized + Zeroize, Self: RevealSecret<Inner = T>,

Available on crate feature ct-eq only.

Constant-time equality for Dynamic<T> — routes through expose_secret().

== is deliberately not implemented. Always use ct_eq.

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

Performs equality comparison in constant time.

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

Always prints [REDACTED] — secrets never appear in debug output.

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Dynamic<String>

Available on crate feature serde-deserialize only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'de> Deserialize<'de> for Dynamic<Vec<u8>>

Available on crate feature serde-deserialize only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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

Unconditionally zeroizes the inner value when the wrapper is dropped.

Warning: Drop does not run under panic = "abort".

fn drop(&mut self)

Executes the destructor for this type.

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

Copies a byte slice to the heap and wraps it.

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

Converts to this type from the input type.

impl From<&str> for Dynamic<String>

Copies a string to the heap and wraps it.

fn from(input: &str) -> Self

Converts to this type from the input type.

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

Zero-copy wrapping of an already-boxed value.

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

Converts to this type from the input type.

impl<T: 'static + Zeroize> From<T> for Dynamic<T>

Boxes the value and wraps it.

fn from(value: T) -> Self

Converts to this type from the input type.

impl RevealSecret for Dynamic<String>

fn into_inner(self) -> InnerSecret<String>

where Self: Sized, Self::Inner: Sized + Default + Zeroize,

Consumes self and returns the inner String wrapped in crate::InnerSecret.

Allocation note: allocates one small Box<String> sentinel (24 bytes on 64-bit) before the swap. If that allocation panics (OOM), self.inner is unchanged and Dynamic::drop zeroizes the real secret during unwind — confidentiality is preserved. This is the same OOM-safety pattern used by from_protected_bytes and deserialize_with_limit.

See RevealSecret::into_inner for full documentation including the redacted Debug behavior.

type Inner = String

The inner secret type being revealed.

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

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

Provides scoped (recommended) read-only access to the secret.

fn expose_secret(&self) -> &String

Returns a direct (auditable) read-only reference to the secret.

fn len(&self) -> usize

Returns the length of the secret in bytes.

fn is_empty(&self) -> bool

Returns true if the secret is empty.

impl<T: Zeroize> RevealSecret for Dynamic<Vec<T>>

fn into_inner(self) -> InnerSecret<Vec<T>>

where Self: Sized, Self::Inner: Sized + Default + Zeroize,

Consumes self and returns the inner Vec<T> wrapped in crate::InnerSecret.

Allocation note: allocates one small Box<Vec<T>> sentinel (24 bytes on 64-bit) before the swap. If that allocation panics (OOM), self.inner is unchanged and Dynamic::drop zeroizes the real secret during unwind — confidentiality is preserved. This is the same OOM-safety pattern used by from_protected_bytes and deserialize_with_limit.

See RevealSecret::into_inner for full documentation including the redacted Debug behavior.

type Inner = Vec<T>

The inner secret type being revealed.

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

where F: FnOnce(&Vec<T>) -> R,

Provides scoped (recommended) read-only access to the secret.

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

Returns a direct (auditable) read-only reference to the secret.

fn len(&self) -> usize

Returns the length of the secret in bytes.

fn is_empty(&self) -> bool

Returns true if the secret is empty.

impl RevealSecretMut for Dynamic<String>

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

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

Provides scoped (recommended) mutable access to the secret.

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

Returns a direct (auditable) mutable reference to the secret.

impl<T: Zeroize> RevealSecretMut for Dynamic<Vec<T>>

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

where F: FnOnce(&mut Vec<T>) -> R,

Provides scoped (recommended) mutable access to the secret.

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

Returns a direct (auditable) mutable reference to the secret.

impl<T: Zeroize + SerializableSecret> Serialize for Dynamic<T>

Available on crate feature serde-serialize only.

Opt-in serialization — requires serde-serialize feature and SerializableSecret marker. Serialization exposes the full secret — audit every impl.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Write for Dynamic<Vec<u8>>

Available on crate feature std only.

Streams bytes directly into the protected buffer via RevealSecretMut.

Data flows into the wrapper — this is a pure security improvement over accumulating plaintext in a bare Vec<u8> before wrapping.

Example

use std::io::Write;
use secure_gate::Dynamic;

let mut secret = Dynamic::<Vec<u8>>::new(vec![]);
secret.write_all(b"decrypted payload").unwrap();

// Secret material was protected from the first byte —
// no intermediate unprotected buffer ever existed.

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

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

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

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

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

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

Zeroizes the inner value (including Vec/String spare capacity).

Warning: does not run under panic = "abort".

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>

Marker confirming that Dynamic<T> always zeroizes on drop.