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

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