secure-gate

A zero-overhead, no_std-compatible secret wrapper with automatic zeroization.

Key Features Summary

secure-gate is designed for seamless, safe secret handling with zero runtime overhead when features are disabled. Core highlights:

• Auto-Gating: Switches between SecretBox<T> + zeroization (default zeroize feature) and plain Box<T> fallback for minimal builds—no code changes required.
• No-Std Native: Full no_std + alloc support for embedded systems.
• Safe & Ergonomic: All public API in 100% safe Rust; secure! macro for quick construction; aliases like SecurePassword (immutable default), SecurePasswordBuilder (mutable opt-in), and SecureKey32.
• Redacted & Zeroized: Automatic Debug redaction ("[REDACTED]"); best-effort zeroization on drop/mutation via zeroize.
• Serde-Ready: Opt-in serialization of secrets (explicitly exposes the secret in serialized form, e.g., JSON strings; protect output bytes appropriately).
• Fuzz-Hardened: 5 libFuzzer targets running 300 CPU minutes nightly.
• Zero-Alloc Fixed Secrets: Stack-only types for keys/nonces (default via stack feature) — no heap, cache-local, #![no_global_oom] friendly.

Installation

Add this to your Cargo.toml:

[dependencies]

secure-gate = "0.3.2"

Usage

use secure_gate::{SecurePassword, SecurePasswordBuilder, Secure};

let password: SecurePassword = "hunter2".into();  // Immutable default, zeroized on drop

let key = Secure::<[u8; 32]>::new(rand::random());  // generic fixed-size (heap for dynamic fallbacks)
let token = Secure::<Vec<u8>>::new(vec![...]);  // dynamic buffer

// Scoped mutation (preferred for mutable cases)
let mut pw_mut: SecurePasswordBuilder = SecurePasswordBuilder::new("base".to_string());
pw_mut.expose_mut().expose_secret_mut().push_str("!!!");
pw_mut.finish_mut();  // reduce excess capacity via shrink_to_fit (best-effort; no scrub of freed memory)

// Convert to immutable form (zeroizes the builder)
let pw: SecurePassword = pw_mut.into_password();  // or .build()

// Extraction (use sparingly)
let bytes: Vec<u8> = token.into_inner();  // original zeroized immediately

Note: SecurePasswordMut is deprecated in v0.3.1 — use SecurePasswordBuilder instead.

Zero-Allocation Fixed-Size Secrets (Default)

For keys/nonces/IVs, aliases like SecureKey32 default to stack-only Zeroizing<[u8; N]> — no heap, deterministic, side-channel minimal:

use secure_gate::{SecureKey32, SecureNonce12};
use secure_gate::stack::{key32, nonce12};

static AES_KEY: SecureKey32 = key32([0x42; 32]);  // const-eligible!
let key: SecureKey32 = SecureKey32::new(rand::random::<[u8; 32]>());  // from RNG
let nonce: SecureNonce12 = nonce12([0u8; 12]);

// Access: deref to inner slice/array
assert_eq!(&*key, &[0x42; 32]);

Falls back to Secure<[u8; N]> if stack disabled. Ideal for crypto hot paths (rustls/ring-style).

Fuzzing Configuration

• 5 libFuzzer targets running nightly
• 300 CPU minutes of continuous fuzzing on GitHub Actions

Dependencies

[dependencies]

secrecy = { version = "0.10.3", optional = true, default-features = false }

zeroize = { version = "1.8", optional = true, default-features = false, features = [

  "alloc",

  "zeroize_derive",

] }

serde = { version = "1.0", features = ["derive"], optional = true }

Features

Zeroization Guarantees

Secure<T> provides best-effort memory zeroization on drop/mutation via the zeroize crate:

• What It Does: Explicitly overwrites secret bytes (up to .len() for dynamic types like Vec/String) using volatile operations that resist compiler optimization.
• Platform Coverage: Works on all stable Rust targets (x86, ARM, RISC-V, etc.) via portable intrinsics. No guarantees against hardware leaks (e.g., cache side-channels)—use constant-time primitives alongside.
• Limitations: Only affects the wrapped value; doesn't secure against copies, logs, or kernel dumps. For full protection, avoid extraction (into_inner) and use scoped expose_mut().
• finish_mut: After mutations, call this to reduce excess capacity (for Vec<u8>, String) via shrink_to_fit(). This is best-effort—some allocators may not shrink—and does not overwrite freed memory (old secrets may persist until allocator/OS reuse). Zeroization on drop still covers only the used portion (up to .len()).
• Dynamic Container Caveats: For growable types like Vec<u8> or String, safe Rust cannot zero the full historical capacity (e.g., after truncate or realloc). Only the current slice up to .len() is overwritten on drop. Avoid patterns like filling a large buffer with secrets then truncating to small length—opt for fixed-size where possible or explicitly zero excess via expose_mut().fill(0) before shrinking.
• Unsafe-Wipe Fast Path: When enabled, Secure<String> uses unsafe for zero-allocation wiping (preserves len/cap)—safe for used buffer only. Null bytes are valid UTF-8; no invariants broken. Opt-in for performance (e.g., high-frequency secrets); safe path used otherwise (allocates temp zeros).
• Fallback Mode: Disabled without zeroize feature—treat as plain Box<T>.
• Stack Aliases Note: Fixed-size types like SecureKey32 use Zeroizing<[u8; N]> by default (via stack feature) for zero-overhead zeroization — same guarantees, no heap.

For details, see zeroize docs.

Contribution

Contributions welcome! Please submit PRs with tests/fuzz targets.

Changelog

See CHANGELOG.md for detailed release notes.

License

Licensed under MIT OR Apache-2.0