Crate sanitization 

Dependency-free secret memory sanitization for no_std Rust.

The primary type is SecretBytes, a fixed-size clear-on-drop container designed for secrets that are controlled from creation through destruction.

Clearing routes through a small internal volatile-write backend. That backend uses one isolated unsafe boundary so the optimizer cannot remove secret clearing as a dead store.

The ct module provides dependency-free data-oblivious primitives such as ct::Choice, ct::ConstantTimeEq, and explicit ct::Choice::declassify boundaries. Its claim is no secret-dependent control flow or memory access under documented conditions, not identical wall-clock timing on every target.

Important limits:

• Safe Rust cannot soundly scrub old stack frames created by prior moves.
• Process abort prevents destructors and post-closure cleanup from running.
• SIMD stores, broad memory policy, and target-specific hardening need target-specific unsafe code and platform policy.
• Platform memory locking is available only through the explicit memory-lock feature on supported Linux, Android, macOS, iOS, Windows, and BSD targets. On WASM, memory-lock must be paired with wasm-compat to expose volatile-only compatibility types without host memory locking. The same feature also enables pooled slots with SecretPool on supported targets.
• Locked, pooled, and guarded canary integrity checks are available only through the explicit canary-check feature on supported targets.
• OS-CSPRNG canary generation is available only through the explicit random-canary feature.
• x86_64/AArch64 assembly-backed comparison is available only through the explicit asm-compare feature.
• High-assurance fail-closed profiles are available through strict-ct, strict-canary-check, and require-fork-exclusion.
• x86_64 cache-line eviction is available only through the explicit cache-flush feature.
• Proc-macro derives are available only through the explicit derive feature. The default build remains dependency-free.
• zeroize, subtle, and serde integration are available only through explicit zeroize-interop, subtle-interop, and serde features. They are off by default.
• Fixed-size lifetime enforcement is available only through the std feature and ExpiringSecretBytes.
• Guard-page allocation is available only through the explicit guard-pages feature on supported Linux, Android, macOS, iOS, Windows, and BSD targets.
• WASM has no kernel page table, mlock, mprotect, or native volatile semantics. Base secret containers compile on WASM. memory-lock exposes volatile-only compatibility types on WASM only when wasm-compat is also enabled, so callers explicitly acknowledge the reduced guarantees. guard-pages is rejected at compile time on WASM.

Modules

cache_flush

ct

Data-oblivious primitives for secret-handling code.

hardware

Traits for integrating external hardware-backed secret providers.

register_scrub

Architecture-specific register scrubbing helpers.

unsafe_wipe

Explicit volatile-write backend for ordinary mutable buffers.

Macros

secure_drop_struct

Declare a struct and generate SecureSanitize plus Drop.

secure_sanitize_struct

Declare a struct and generate SecureSanitize for all fields.

Structs

AlreadyConsumedError

Error returned after a ReadOnceSecret has already been consumed.

CanaryCorruptedError

Error returned when a checked locked secret detects canary corruption.

ExpiringSecretBytes

Fixed-size secret bytes with std lifetime enforcement.

GuardPageError

Error returned by guarded secret allocation operations.

GuardedSecretVec

Dynamic secret bytes stored between inaccessible platform guard pages.

LengthError

Error returned when a caller provides a buffer with the wrong length.

LockedSecretBytes

Fixed-size secret bytes stored in a private locked platform mapping.

LockedSecretVec

LockedSecretVec fills the gap between crate::SecretVec and crate::GuardedSecretVec. It supports runtime-length secret bytes in platform-locked memory without adding guard pages, which keeps memory overhead lower for large PEM/DER material, tokens, or generated secrets where page-fence protection is not required.

MemoryLockError

Error returned by platform memory-locking operations.

MonotonicExpiringSecretBytes

Fixed-size secret bytes with caller-provided monotonic lifetime enforcement.

ReadOnceSecret

Clear-on-drop wrapper that can be consumed exactly once.

Secret

Clear-on-drop wrapper for non-byte secret types.

SecretBytes

Fixed-size secret byte storage with automatic sanitization on drop.

SecretExpiredError

Error returned when an expiring secret has exceeded its configured lifetime.

SecretPool

Fixed-slot arena for many same-size secrets inside one locked mapping.

SecretPoolSlot

A live fixed-size secret slot allocated from a SecretPool.

SecretString

Heap-allocated secret UTF-8 text with clear-on-drop behavior.

SecretVec

Heap-allocated secret bytes with clear-on-drop behavior.

SplitSecretBytes

Fixed-size N-of-N XOR split secret storage.

Enums

ExpiringSecretError

Error returned by expiring secret operations.

GuardPageOperation

Platform guard-page operation that failed.

GuardedSecretVecGenerateError

Error returned when fallible guarded byte generation fails.

LockedSecretBytesCheckedCopyError

Error returned by checked locked-secret copy operations.

LockedSecretBytesError

Error returned when constructing LockedSecretBytes from a slice.

LockedSecretBytesGenerateError

Error returned when fallible locked secret byte generation fails.

LockedSecretVecFillError

Error returned when in-place locked dynamic byte filling fails.

LockedSecretVecGenerateError

Dynamic secret bytes stored in a private locked platform mapping.

MemoryLockOperation

Platform memory-locking operation that failed.

SplitSecretError

Error returned by split-secret construction.

Traits

MonotonicClock

Caller-provided monotonic tick source for no-std expiring secrets.

SecureSanitize

Shared trait for values that can clear their own sensitive contents.

Functions

sanitize_bytes

Clear ordinary mutable bytes with volatile writes.

sanitize_bytes_best_effort

Compatibility alias for sanitize_bytes.

sanitize_bytes_multi_pass

Clear ordinary mutable bytes with an explicit three-pass volatile pattern.

secure_replace

Sanitize a value before replacing it.

Derive Macros

ConditionallySelectable

Derive sanitization::ct::ConditionallySelectable for structs.

ConstantTimeEq

Derive sanitization::ct::ConstantTimeEq for structs.

SecureSanitize

Derive sanitization::SecureSanitize for structs and enums.

SecureSanitizeOnDrop

Derive Drop by calling sanitization::SecureSanitize::secure_sanitize.