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, SecretLen};

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_base32(s)	encoding-base32	Constant-time Base32 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 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 try_from_base32(s: &str) -> Result<Self, Base32Error>

Decodes an uppercase, unpadded Base32 (RFC 4648 §6) 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.

Decoding is strict about the alphabet, case, padding and length, but lenient about non-canonical trailing bits: unused bits in the final group are ignored rather than rejected, so "MZ" and "MY" both decode to [0x66]. Decoding is therefore not injective — two distinct strings can yield the same bytes, and only encoder-produced strings are canonical. Do not use the decoded value to decide that two encoded strings were equal.

impl Dynamic<Vec<u8>>

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_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_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 that protects against closure panics.

The intermediate Vec<u8> is held inside a Zeroizing wrapper for the entire duration of the closure, so any bytes the closure writes are zeroed during stack unwinding if f panics. Constructed via the same Zeroizing + swap pattern used by from_protected_bytes.

impl Dynamic<String>

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

where F: FnOnce(&mut String),

Closure-based constructor that protects against closure panics.

The intermediate String is held inside a Zeroizing wrapper for the entire duration of the closure, so any bytes the closure writes are zeroed during stack unwinding if f panics. Constructed via the same Zeroizing + swap pattern used by from_protected_bytes.

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 (OsRng) via TryRngCore::try_fill_bytes. Requires the rand feature (and alloc, which Dynamic<Vec<u8>> always needs).

Panics

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

Examples

use secure_gate::{Dynamic, RevealSecret, SecretLen};

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

pub fn from_rng<R: TryRngCore + 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 + TryRngCore — 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.

Zeroization scope. Once the upstream deserializer returns a complete Vec<u8>, the value is wrapped in Zeroizing and stays protected for the rest of this function: oversized buffers are zeroized before the error is returned, and an OOM panic in the subsequent Box allocation triggers zeroization on unwind. However, this guarantee does not extend backwards into the deserializer itself. If the upstream Vec<u8> visitor accumulates bytes element-by-element (e.g., a JSON sequence) and fails partway through, the partial buffer is owned by the visitor and dropped as a plain Vec<u8> — not zeroized. In the typical untrusted-input threat model the partial bytes are attacker-controlled (the malformed payload they sent), so the practical disclosure surface is bounded; but if your threat model includes deserialization of trusted-but-corruptible secret material, treat the deserialize step as outside the zeroization boundary and use from_protected_bytes (private API) or new_with for in-process construction instead.

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.

Zeroization scope. Once the upstream deserializer returns a complete String, the value is wrapped in Zeroizing and stays protected for the rest of this function: oversized buffers are zeroized before the error is returned, and an OOM panic in the subsequent Box allocation triggers zeroization on unwind. However, this guarantee does not extend backwards into the deserializer itself. If the upstream String visitor accumulates characters and fails partway through (e.g., on an invalid UTF-8 boundary), the partial buffer is owned by the visitor and dropped as a plain String — not zeroized. In the typical untrusted-input threat model the partial bytes are attacker-controlled (the malformed payload they sent), so the practical disclosure surface is bounded; but if your threat model includes deserialization of trusted-but-corruptible secret material, treat the deserialize step as outside the zeroization boundary and use from_protected_bytes (private API) or new_with for in-process construction instead.

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<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<'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<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.

fn pin_drop(self: Pin<&mut Self>)

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

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

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

fn into_inner(self) -> InnerSecret<T>

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

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

Allocation note: allocates one small Box<T> sentinel (24 bytes for String/Vec 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.

After ownership transfer, capacity-changing mutations on the returned InnerSecret<T> have the same realloc-residue caveats as mutating Dynamic<T> in place; see SECURITY.md.

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

type Inner = T

The inner secret type being revealed.

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

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

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

fn expose_secret(&self) -> &T

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

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

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

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

Provides scoped (recommended) mutable access to the secret.

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

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

impl SecretLen for Dynamic<String>

fn len(&self) -> usize

Returns the number of elements in the secret, matching the underlying container’s len() — element count for Vec<T> and [T; N], byte count for String (where the element is a byte).

fn byte_len(&self) -> usize

Returns the total size of the secret in bytes.

fn is_empty(&self) -> bool

Returns true if the secret is empty.

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

fn len(&self) -> usize

Returns the number of elements in the secret, matching the underlying container’s len() — element count for Vec<T> and [T; N], byte count for String (where the element is a byte).

fn byte_len(&self) -> usize

Returns the total size of the secret in bytes.

fn is_empty(&self) -> bool

Returns true if the secret is empty.

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 ToBase32 for Dynamic<Vec<u8>>

Available on crate feature encoding-base32 only.

Base32 encoding for Dynamic<Vec<u8>>; delegates via with_secret.

Bring the trait into scope: use secure_gate::ToBase32;.

use secure_gate::{Dynamic, ToBase32};

let token: Dynamic<Vec<u8>> = Dynamic::from(&[0xABu8; 4][..]);
assert_eq!(token.to_base32(), "VOV2XKY");

fn to_base32(&self) -> String

Encode bytes as Base32 (RFC 4648 §6 alphabet, uppercase, no padding).

fn to_base32_zeroizing(&self) -> EncodedSecret

Encode bytes as Base32 and wrap the result in crate::EncodedSecret.

impl ToBase64Url for Dynamic<Vec<u8>>

Available on crate feature encoding-base64 only.

Base64url encoding for Dynamic<Vec<u8>>; delegates via with_secret.

Bring the trait into scope: use secure_gate::ToBase64Url;.

use secure_gate::{Dynamic, ToBase64Url};

let token: Dynamic<Vec<u8>> = Dynamic::from(&[0xABu8; 4][..]);
assert_eq!(token.to_base64url(), "q6urqw");

fn to_base64url(&self) -> String

Encode bytes as URL-safe base64 (no padding).

fn to_base64url_zeroizing(&self) -> EncodedSecret

Encode bytes as URL-safe base64 and wrap the result in crate::EncodedSecret.

impl ToBech32 for Dynamic<Vec<u8>>

Available on crate feature encoding-bech32 only.

Bech32 encoding for Dynamic<Vec<u8>>; delegates via with_secret.

Bring the trait into scope: use secure_gate::ToBech32;.

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

Fallibly encodes bytes as a Bech32 (BIP-173) string with the given HRP.

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

Fallibly encodes bytes as Bech32 and wraps the result in crate::EncodedSecret.

impl ToBech32m for Dynamic<Vec<u8>>

Available on crate feature encoding-bech32m only.

Bech32m encoding for Dynamic<Vec<u8>>; delegates via with_secret.

Bring the trait into scope: use secure_gate::ToBech32m;.

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

Fallibly encodes bytes as a Bech32m (BIP-350) string with the given HRP.

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

Fallibly encodes bytes as Bech32m and wraps the result in crate::EncodedSecret.

impl ToHex for Dynamic<Vec<u8>>

Available on crate feature encoding-hex only.

Hex encoding for Dynamic<Vec<u8>>; delegates via with_secret.

Deliberately not implemented for Dynamic<String> — hex-encoding textual secrets is a design smell; convert explicitly inside with_secret if genuinely needed. Bring the trait into scope: use secure_gate::ToHex;.

use secure_gate::{Dynamic, ToHex};

let token: Dynamic<Vec<u8>> = Dynamic::from(&[0xDEu8, 0xAD][..]);
assert_eq!(token.to_hex(), "dead");

fn to_hex(&self) -> String

Encode bytes as lowercase hexadecimal.

fn to_hex_upper(&self) -> String

Encode bytes as uppercase hexadecimal.

fn to_hex_zeroizing(&self) -> EncodedSecret

Encode bytes as lowercase hexadecimal and wrap the result in crate::EncodedSecret.

fn to_hex_upper_zeroizing(&self) -> EncodedSecret

Encode bytes as uppercase hexadecimal and wrap the result in crate::EncodedSecret.

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, so no intermediate unprotected Vec<u8> is accumulated before wrapping.

Growth wipes the outgoing buffer

Writing past the current capacity cannot simply delegate to Vec: Vec would reallocate, copy the secret into the new allocation, and hand the old one back to the allocator with the plaintext still in it. This impl grows by hand instead — it allocates the larger buffer, copies, zeroizes the old buffer (contents and spare capacity), and only then releases it.

Pre-sizing with Vec::with_capacity avoids the copy altogether and is worth doing when the length is known up front:

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

let payload = b"decrypted payload";

// Pre-sized: no growth, so no copy and nothing to wipe.
let mut secret = Dynamic::<Vec<u8>>::new(Vec::with_capacity(payload.len()));
secret.write_all(payload).unwrap();

This addresses only the buffer this impl owns. A caller who grows the Vec themselves through with_secret_mut or expose_secret_mut holds &mut Vec<u8> directly, and their reallocation is outside this crate’s control — see the heap-reallocation residue section in SECURITY.md.

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.