Struct Fixed 

pub struct Fixed<T: Zeroize> { /* private fields */ }

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

Always available. Inner type must implement Zeroize. Zero-cost stack-allocated wrapper for fixed-size secrets.

Always available. Inner type must implement Zeroize for automatic zeroization on drop.

No Deref, AsRef, or Copy by default — all access requires expose_secret() or with_secret() (scoped, preferred). For construction of Fixed<[u8; N]>, new_with is the matching scoped constructor — it writes directly into the wrapper’s storage and avoids any intermediate stack copy. new(value) remains available as the ergonomic default. Debug always prints [REDACTED]. Performance indistinguishable from raw arrays.

Implementations

impl<T: Zeroize> Fixed<T>

pub const fn new(value: T) -> Self

Creates a new Fixed<T> by wrapping a value.

impl<const N: usize> Fixed<[u8; N]>

Construction and ergonomic encoding helpers for Fixed<[u8; N]>.

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

where F: FnOnce(&mut [u8; N]),

Writes directly into the wrapper’s storage via a user-supplied closure, eliminating the intermediate stack copy that new may produce.

The array is zero-initialized before the closure runs. Prefer this over new(value) when minimizing stack residue matters (long-lived keys, high-assurance environments).

Examples

use secure_gate::Fixed;

let secret = Fixed::<[u8; 4]>::new_with(|arr| arr.fill(0xAB));

pub fn to_hex(&self) -> String

Encodes the secret bytes as a lowercase hex string.

Delegates to ToHex::to_hex on the inner [u8; N]. 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 [u8; N]. 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 [u8; N]. Requires the encoding-base64 feature.

impl<const N: usize> Fixed<[u8; N]>

pub fn from_random() -> Self

Fills a new [u8; N] with 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. Heap-free and works in no_std / no_alloc builds.

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::{Fixed, RevealSecret};

let key: Fixed<[u8; 32]> = Fixed::from_random();
assert_eq!(key.len(), 32);

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

Fills a new [u8; N] 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. Heap-free.

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::Fixed;

let key: Fixed<[u8; 16]> = Fixed::from_rng(&mut OsRng).expect("rng fill");

Deterministic fill (tests) with a seedable generator:

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

let mut rng = StdRng::from_seed([1u8; 32]);
let key: Fixed<[u8; 16]> = Fixed::from_rng(&mut rng).expect("rng fill");

impl<const N: usize> Fixed<[u8; N]>

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

Decodes a lowercase hex string into Fixed<[u8; N]>.

The decoded bytes are held in a Zeroizing<Vec<u8>> until copied onto the stack array, so the temporary heap buffer is zeroed even if a panic occurs mid-flight.

Errors

Returns HexError::InvalidLength if the decoded length does not equal N, or a parse error if the input is not valid hex.

Note

Unlike Dynamic::try_from_hex, the secret lives on the stack inside a [u8; N]. Stack residue behaviour after the Fixed is dropped and zeroized is discussed in SECURITY.md.

impl<const N: usize> Fixed<[u8; N]>

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

Decodes an unpadded Base64url string into Fixed<[u8; N]>.

The decoded bytes are held in a Zeroizing<Vec<u8>> until copied onto the stack array, so the temporary heap buffer is zeroed even if a panic occurs mid-flight.

Errors

Returns Base64Error::InvalidLength if the decoded length does not equal N, or a parse error if the input is not valid Base64url.

Note

Unlike Dynamic::try_from_base64url, the secret lives on the stack inside a [u8; N]. Stack residue behaviour after the Fixed is dropped and zeroized is discussed in SECURITY.md.

impl<const N: usize> Fixed<[u8; N]>

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

Decodes a Bech32 (BIP-173) string into Fixed<[u8; N]>.

Warning

The HRP is not validated — any HRP will be accepted as long as the checksum is valid and the payload length equals N. 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 Fixed<[u8; N]>, validating that the HRP matches expected_hrp (case-insensitive).

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

impl<const N: usize> Fixed<[u8; N]>

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

Decodes a Bech32m (BIP-350) string into Fixed<[u8; N]>.

Warning

The HRP is not validated — any HRP will be accepted as long as the checksum is valid and the payload length equals N. 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 Fixed<[u8; N]>, validating that the HRP matches expected_hrp (case-insensitive).

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

Trait Implementations

impl<T: Zeroize + CloneableSecret> Clone for Fixed<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 Fixed<T>

where T: ConstantTimeEq + Zeroize,

Available on crate feature ct-eq only.

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

Performs equality comparison in constant time.

impl<T: Zeroize> Debug for Fixed<T>

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

Formats the value using the given formatter.

impl<'de, const N: usize> Deserialize<'de> for Fixed<[u8; N]>

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: Zeroize> Drop for Fixed<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<const N: usize, T: Zeroize> ExposeSecret<[T; N]> for Fixed<[T; N]>

fn expose_secret(&self) -> &[T; N]

Returns a shared reference to the inner secret.

impl<const N: usize, T: Zeroize> ExposeSecretMut<[T; N]> for Fixed<[T; N]>

fn expose_secret_mut(&mut self) -> &mut [T; N]

Returns a mutable reference to the inner secret.

impl<const N: usize> From<[u8; N]> for Fixed<[u8; N]>

fn from(arr: [u8; N]) -> Self

Converts to this type from the input type.

impl<T: Clone + Zeroize, const N: usize> From<Fixed<[T; N]>> for Secret<[T; N]>

Converts a Fixed<[T; N]> into Secret<[T; N]>.

fn from(f: Fixed<[T; N]>) -> Self

Converts to this type from the input type.

impl<T: Clone + Zeroize, const N: usize> From<Secret<[T; N]>> for Fixed<[T; N]>

Converts Secret<[T; N]> into a Fixed<[T; N]>.

fn from(s: Secret<[T; N]>) -> Self

Converts to this type from the input type.

impl<const N: usize, T: Zeroize> RevealSecret for Fixed<[T; N]>

Explicit access to immutable [Fixed<[T; N]>] contents.

fn into_inner(self) -> InnerSecret<[T; N]>

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

Consumes self and returns the inner [T; N] wrapped in crate::InnerSecret.

Zero cost — no allocation. The sentinel placed in self.inner is [T::default(); N] (already zeroed for u8), so Fixed::drop zeroizes an already-zero array — a harmless no-op.

See RevealSecret::into_inner for full documentation including the Default bound rationale and redacted Debug behavior.

type Inner = [T; N]

The inner secret type being revealed.

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

where F: FnOnce(&[T; N]) -> R,

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

fn expose_secret(&self) -> &[T; N]

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<const N: usize, T: Zeroize> RevealSecretMut for Fixed<[T; N]>

Explicit access to mutable [Fixed<[T; N]>] contents.

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

where F: FnOnce(&mut [T; N]) -> R,

Provides scoped (recommended) mutable access to the secret.

fn expose_secret_mut(&mut self) -> &mut [T; N]

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

impl<T: Zeroize + SerializableSecret> Serialize for Fixed<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<const N: usize> TryFrom<&[u8]> for Fixed<[u8; N]>

type Error = FromSliceError

The type returned in the event of a conversion error.

fn try_from(slice: &[u8]) -> Result<Self, Self::Error>

Performs the conversion.

impl<T: Zeroize> Zeroize for Fixed<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: Zeroize> ZeroizeOnDrop for Fixed<T>