Struct Dynamic 

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

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

Requires alloc feature. Inner type must implement Zeroize. Zero-cost heap-allocated wrapper for variable-length secrets.

Requires alloc. Inner type must implement Zeroize for automatic zeroization on drop (including spare capacity in Vec/String).

No Deref, AsRef, or Copy by default — all access requires expose_secret() or with_secret() (scoped, preferred). For the common concrete types, Dynamic::<Vec<u8>>::new_with and Dynamic::<String>::new_with are the matching scoped constructors — closures that write directly into the wrapper. new(value) remains available as the ergonomic default. Debug always prints [REDACTED].

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.

Delegates to ToHex::to_hex on the inner Vec<u8>. Requires the encoding-hex feature.

pub fn to_hex_upper(&self) -> String

Encodes the secret bytes as an uppercase hex string.

Delegates to ToHex::to_hex_upper on the inner Vec<u8>. Requires the encoding-hex feature.

pub fn to_base64url(&self) -> String

Encodes the secret bytes as an unpadded Base64url string.

Delegates to ToBase64Url::to_base64url on the inner Vec<u8>. Requires the encoding-base64 feature.

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. In rand 0.9, OsRng is a zero-sized handle to the OS generator (not user-seedable). 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. Pass OsRng for the same system entropy as from_random with a fallible interface. Do not use OsRng for deterministic tests — in rand 0.9 it is a unit struct backed by the OS and is not seedable; use a seedable PRNG such as StdRng with SeedableRng instead. Requires the rand feature and alloc (implicit — Dynamic<T> itself requires it).

Errors

Returns R::Error if try_fill_bytes fails.

Examples

System RNG (same source as from_random, Result-based):

use rand::rngs::OsRng;
use secure_gate::Dynamic;

let nonce: Dynamic<Vec<u8>> = Dynamic::from_rng(24, &mut OsRng).expect("rng fill");

Deterministic fill (tests) with a seedable generator:

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 try_from_hex(s: &str) -> Result<Self, HexError>

Decodes a lowercase hex 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_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_unchecked(s: &str) -> Result<Self, Bech32Error>

Decodes a Bech32 (BIP-173) 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.

Warning

The HRP is not validated — any HRP will be accepted as long as the checksum is valid. For security-critical code where cross-protocol confusion must be prevented, use try_from_bech32.

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

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

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

Prefer this over try_from_bech32_unchecked in security-critical code to prevent cross-protocol confusion attacks.

impl Dynamic<Vec<u8>>

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

Decodes a Bech32m (BIP-350) 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.

Warning

The HRP is not validated — any HRP will be accepted as long as the checksum is valid. For security-critical code where cross-protocol confusion must be prevented, use try_from_bech32m.

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

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

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

Prefer this over try_from_bech32m_unchecked in security-critical code to prevent cross-protocol confusion attacks.

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.

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,

Available on crate feature ct-eq only.

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

Performs equality comparison in constant time.

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

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>

fn drop(&mut self)

Executes the destructor for this type.

impl ExposeSecret<String> for Dynamic<String>

fn expose_secret(&self) -> &String

Returns a shared reference to the inner secret.

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

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

Returns a shared reference to the inner secret.

impl ExposeSecretMut<String> for Dynamic<String>

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

Returns a mutable reference to the inner secret.

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

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

Returns a mutable reference to the inner secret.

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

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

Converts to this type from the input type.

impl From<&str> for Dynamic<String>

fn from(input: &str) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl From<Dynamic<String>> for Secret<String>

Converts a Dynamic<String> into Secret<String>.

fn from(d: Dynamic<String>) -> Self

Converts to this type from the input type.

impl From<Dynamic<String>> for SecretBox<String>

Converts a Dynamic<String> back into a SecretBox<String>.

Clones the inner String. Both the source and the new wrapper are zeroized on drop.

fn from(d: Dynamic<String>) -> Self

Converts to this type from the input type.

impl From<Dynamic<String>> for SecretString

Converts a Dynamic<String> into a SecretString (= SecretBox<str>).

Clones the inner string. Both ends are zeroized on drop.

fn from(d: Dynamic<String>) -> Self

Converts to this type from the input type.

impl<S: Clone + Zeroize + 'static> From<Dynamic<Vec<S>>> for SecretBox<Vec<S>>

Converts a Dynamic<Vec<S>> back into a SecretBox<Vec<S>>.

Clones the inner Vec. Both ends are zeroized on drop.

fn from(d: Dynamic<Vec<S>>) -> Self

Converts to this type from the input type.

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

Converts a Dynamic<Vec<T>> into Secret<Vec<T>>.

fn from(d: Dynamic<Vec<T>>) -> Self

Converts to this type from the input type.

impl From<Secret<String>> for Dynamic<String>

Converts Secret<String> into a Dynamic<String>.

fn from(s: Secret<String>) -> Self

Converts to this type from the input type.

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

Converts Secret<Vec<T>> into a Dynamic<Vec<T>>.

fn from(s: Secret<Vec<T>>) -> Self

Converts to this type from the input type.

impl<S: Clone + Zeroize + 'static> From<SecretBox<S>> for Dynamic<S>

Converts a SecretBox<S> into a Dynamic<S> (primary migration path).

Requires S: Clone because the inner Box<S> cannot be moved out of SecretBox without unsafe code (SecretBox has a Drop impl). The clone is immediately wrapped in Dynamic and the original is zeroized on drop.

For zero-copy migration, construct Dynamic<S> directly instead.

fn from(sb: SecretBox<S>) -> Self

Converts to this type from the input type.

impl From<SecretBox<str>> for Dynamic<String>

Converts a SecretString (= SecretBox<str>) into a Dynamic<String>.

Clones the inner str into a new String. Both ends are zeroized on drop.

fn from(sb: SecretString) -> Self

Converts to this type from the input type.

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

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.

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>

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>