Crate secure_gate 

Zero-cost secure wrappers for secrets — Dynamic<T> for heap-allocated variable-length data, Fixed<T> for stack-allocated fixed-size data.

This crate provides explicit, guarded wrappers for sensitive values (e.g. keys, tokens, ciphertexts) with controlled exposure via .expose_secret() / .expose_secret_mut(). No accidental leaks via Deref, AsRef, or implicit conversions.

Quickstart

Add this to your Cargo.toml:

[dependencies]
secure-gate = "0.7.0-rc.14"

Here’s a basic example with Fixed for a stack-allocated secret (no extra features needed):

use secure_gate::Fixed;

// Wrap a fixed-size secret (e.g., a 32-byte key)
let secret = Fixed::<[u8; 32]>::new([42; 32]);

// Expose it temporarily for use, zeroizing afterward
let value = secret.expose_secret(|exposed| {
    // Do something with `exposed` (e.g., encrypt)
    exposed[0]
});

For dynamic secrets, enable the alloc feature and use Dynamic<T> similarly.

Check README.md for more examples and feature flags.

Equality Options

ConstantTimeEq (via ct-eq feature): Direct byte-by-byte constant-time comparison using subtle. Best for small/fixed-size secrets (< ~256–512 bytes) where speed matters most.

ConstantTimeEqExt (via ct-eq-hash feature): BLAKE3 hash -> constant-time compare on fixed 32-byte digest. Faster for large/variable secrets (e.g. ML-KEM ciphertexts ~1–1.5 KiB, ML-DSA signatures ~2–4 KiB), with length hiding and optional keyed mode (rand for per-process random key).

See the ConstantTimeEqExt trait documentation for performance numbers, security properties (probabilistic, timing-safe), and guidance on when to choose each (or hybrid).

Macros

dynamic_alias

Creates a type alias for a dynamic-sized heap-allocated secure secret.

dynamic_generic_alias

Creates a generic dynamic-sized heap-allocated secure secret type.

fixed_alias

Creates a type alias for a fixed-size stack-allocated secure secret.

fixed_generic_alias

Creates a generic fixed-size stack-allocated secure secret type.

Structs

Dynamic

Re-export of the Dynamic type. Dynamic-sized heap-allocated secure secret wrapper.

Fixed

Re-export of the Fixed type.

Enums

Base64Error

Re-export of Base64Error for convenience when using base64 decoding. Error type for Base64 decoding operations.

Bech32Error

Re-export of Bech32Error for convenience when using bech32 encoding/decoding. Error type for Bech32 operations (encoding and decoding).

DecodingError

Re-export of DecodingError for convenience in decoding operations. Unified error type for decoding operations across formats.

HexError

Re-export of HexError for convenience when using hex decoding. Error type for Hex decoding operations.

Traits

CloneableSecret

Implement this trait on types that require safe duplication while maintaining security guarantees. The trait itself is a marker and does not provide methods, but implementations must ensure proper zeroization.

ConstantTimeEq

Re-export of the traits. Trait for constant-time equality comparison to prevent timing attacks.

ConstantTimeEqExt

ExposeSecret

Trait for read-only access to secrets, including metadata.

ExposeSecretMut

Usage

FromBase64UrlStr

Extension trait for decoding URL-safe base64 strings to byte data.

FromBech32Str

Extension trait for decoding Bech32 strings to byte data.

FromBech32mStr

FromHexStr

Extension trait for decoding hex strings to byte data.

SecureDecoding

Marker trait for types that support secure decoding operations.

SecureEncoding

Marker trait for types that support secure encoding operations.

SerializableSecret

Implement this on types that can be deliberately serialized while maintaining security. The trait itself is a marker and does not provide methods, but implementations must ensure that serialization does not leak secrets unintentionally.

ToBase64Url

Extension trait for encoding byte data to URL-safe base64 strings (no padding).

ToBech32

ToBech32m

Extension trait for encoding byte data to Bech32m strings with a specified Human-Readable Part (HRP).

ToHex

Extension trait for encoding byte data to lowercase hexadecimal strings.