secrecy

secrecy is a small, forbid(unsafe_code) Rust crate built around one idea: a secret value (an API key, password, or private key) should be structurally hard to leak by accident. Its core SecretBox<T> type wraps any value so it cannot be printed via Debug, serialized, or copied without going through an explicit ExposeSecret trait call - forcing every place a secret is actually read to be visible and intentional in the code. When a SecretBox is dropped, its contents are zeroed out via the zeroize crate so the plaintext doesn’t linger in memory.

Maintained by iqlusion (part of the iqlusioninc/crates collection of Rust crates) alongside cryptography and key-management crates like zeroize and bip32, secrecy has become a common building block wherever Rust code handles credentials, tokens, or cryptographic key material and wants the type system to help prevent leaking them into logs or error messages.

What You Get

• SecretBox<T>, a generic wrapper that stores any value as a secret and blocks its accidental exposure via Debug or logging
• The ExposeSecret trait, requiring callers to explicitly opt in every time they need the underlying secret value
• Automatic memory zeroing on drop, built on the zeroize crate, so secret bytes don’t remain readable in freed memory
• Optional serde support (feature-gated) for deserializing owned secret values while minimizing accidental copies
• no_std-compatible design (with alloc), making it usable in embedded and constrained environments

Common Use Cases

• Wrapping API keys, tokens, or passwords in application config structs so they can’t be accidentally printed in logs or error messages
• Holding cryptographic key material in memory with a guarantee that it’s zeroed out as soon as it goes out of scope
• Passing secrets through a codebase where the type system should force every read site to be an explicit, auditable expose_secret() call
• Deserializing secret values from config files or environment variables via serde without leaving extra plaintext copies around

Under The Hood

Architecture - The crate is intentionally minimal (a single ~350-line src/lib.rs): SecretBox<T> is a newtype wrapper around T, with manual (non-derived) implementations of Debug/Clone/etc. that either omit the inner value or route through explicit APIs, and a Drop impl that calls into the zeroize crate’s Zeroize trait to overwrite the memory before deallocation. The ExposeSecret trait is the single sanctioned way to read the wrapped value, keeping every access point grep-able and auditable. Tech Stack - Pure Rust, no_std-compatible with the alloc feature, depends only on zeroize (with optional serde support gated behind a cargo feature), uses Rust edition 2024 and requires Rust 1.85+; part of the iqlusioninc/crates Cargo workspace alongside related crates like zeroize and bip32. Code Quality - The crate carries a forbid(unsafe_code) attribute and a “Safety Dance” badge, signaling a deliberate constraint against unsafe blocks; being a thin wrapper crate, its correctness rests heavily on zeroize’s tested zeroing guarantees rather than a large internal test suite of its own. API Design - The API surface is deliberately tiny - construct a SecretBox, and read it only via expose_secret() - trading flexibility for a hard-to-misuse guarantee, which is the entire point of the crate.