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

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

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

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

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>