Crate sanitization

Expand description

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. Secret-controlled indexes and scalars use clear-on-drop ct::SecretIndex and ct::SecretScalar owners, while ct::SecretCtOption and ct::SecretCtResult manage secret-bearing dummy and unselected state. 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. Under std, sanitize_then_abort clears one explicitly supplied root before a deliberate abort; it does not intercept arbitrary abort paths.
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. The crate’s own Miri unit tests use a test-only aligned-allocation model for lifecycle and clear-before-release checks; modeled report states do not prove that an OS protection was applied. Downstream Miri execution of native mapped constructors is unsupported.
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.
The dependency-free default enables asm-compare, selecting the reviewed x86_64/AArch64 assembly equality backend where available. Builds using default-features = false retain the weaker portable fallback unless they explicitly enable asm-compare.
Fail-closed assembly-backed equal-length byte comparison is available through strict-compare. This feature does not strengthen ordering, selection, lookup, or caller code. Other fail-closed profiles include strict-canary-check and require-fork-exclusion.
Named native profiles bundle reviewed capabilities without claiming that runtime protections succeeded. Use ProtectionRequest to inspect the policy and ProtectionReport to inspect achieved controls.
Checked x86_64 cache-line eviction is available through the explicit cache-flush feature. Other architectures and Miri return a structured unsupported result after sanitizing helpers have still cleared memory.
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.
UTF-8 validation, serde size-limit rejection, and public-length mismatch handling are not data-oblivious operations. Callers must treat validity and length as public metadata when using text or variable-length APIs.
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.

§Migrating From 1.x

Version 2 makes storage stability, CT declassification, derive safety, mapped integrity, and runtime protection outcomes explicit. The complete source-change inventory and replacement examples are maintained in docs/MIGRATION_2.0.md. Generic Secret<T> exposure is governed by the conditional contracts in docs/STORAGE_CONTRACTS.md, and native hardening policy/report semantics are defined in docs/PROTECTION_REPORT.md.

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.
wipe: Safe direct wiping helpers for ordinary buffers. Safe direct wiping helpers for ordinary owned buffers.

Macros§

define_secret_storage_policy: Define an application-owned concrete-type allow-list for AllowlistedSecret.
secure_drop_struct: Declare a struct and generate SecureSanitize plus Drop.
secure_sanitize_struct: Declare a struct and generate SecureSanitize for all fields.

Structs§

AllowlistedSecret: Clear-on-drop secret gated by an application-controlled storage allow-list.
AlreadyConsumedError: Error returned after a ConsumeOnceSecret has already been claimed.
BoundedGuardedSecretString: Guarded UTF-8 text with a permanent type-level byte maximum.
BoundedGuardedSecretVec: Runtime-length guarded bytes with a permanent type-level maximum.
BoundedLockedSecretString: Locked UTF-8 text with a permanent type-level byte maximum.
BoundedLockedSecretVec: Runtime-length locked bytes with a permanent type-level maximum.
BoundedSecretString: Heap-allocated secret UTF-8 text constrained to a public byte limit.
BoundedSecretVec: Heap-allocated secret bytes constrained to a public maximum length.
CanaryCorruptedError: Error returned when a mapped secret’s integrity canaries are corrupted.
CleanupError: Error returned when explicit page-sealed cleanup is incomplete.
CleanupReport: Observable result of explicit page-sealed mapping cleanup.
ConsumeOnceSecret: Clear-on-drop wrapper that permits one scoped secret exposure.
ExpiringSecretBytes: Fixed-size secret bytes with std lifetime enforcement.
ForkProtectionReport: Actual outcome of the requested process-fork behavior.
ForkProtectionRequest: Fork behavior requested for a mapped secret allocation.
GuardPageError: Error returned by guarded secret allocation operations.
GuardedSecretString: UTF-8 text stored between inaccessible platform guard pages.
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.
LockedSecretString: UTF-8 text stored in a private platform mapping locked against paging.
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.
ProtectionError: Error returned when a required runtime protection cannot be established.
ProtectionFailure: Non-secret description of a failed protection operation.
ProtectionReport: Runtime report retained by a mapped secret container.
ProtectionRequest: Runtime protections requested for a mapped secret allocation.
RollbackReport: Cleanup results after a required protection could not be established.
SealedSecretBytes: Fixed-size secret bytes kept on an inaccessible page between accesses.
Secret: Clear-on-drop wrapper for non-byte secret types.
SecretBoxBytes: Fixed-allocation secret bytes with a runtime length.
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.
SecretPoolReport: Point-in-time capacity and lock-efficiency report for a fixed-size pool.
SecretPoolSlot: A live fixed-size secret slot allocated from a SecretPool.
SecretPoolSlotId: Stable identity of one live allocation from a fixed-size secret pool.
SecretString: Heap-allocated secret UTF-8 text with clear-on-drop behavior.
SecretStringLimitError: Error returned when secret UTF-8 text exceeds its declared public limit.
SecretVec: Heap-allocated secret bytes with clear-on-drop behavior.
SecretVecLimitError: Error returned when a dynamic secret exceeds its declared public limit.
SplitSecretBytes: Fixed-size N-of-N XOR split secret storage.

Enums§

BoundedMappedSecretError: Error returned by a permanently bounded mapped-secret mutation.
BoundedSecretStringError: Error returned while converting bounded secret bytes into UTF-8 text.
CleanupState: Outcome of one explicit page-sealed cleanup operation.
ExpiringSecretError: Error returned by expiring secret operations.
ForkPolicy: Desired treatment of secret mappings across process fork.
GuardPageOperation: Platform guard-page operation that failed.
GuardedSecretVecGenerateError: Error returned when fallible guarded byte generation fails.
LockedSecretBytesError: Error returned when constructing LockedSecretBytes from a slice.
LockedSecretBytesFillError: Error returned while fallibly filling a new locked fixed-size mapping.
LockedSecretBytesGenerateError: Error returned when fallible locked secret byte generation fails.
LockedSecretInitError: Error returned while initializing locked fixed-size secret storage.
LockedSecretInitializeError: Error returned while initializing an existing locked fixed-size mapping.
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.
PoolInitError: Error returned while initializing a locked pool slot from bytes.
ProtectedSecretFillError: Error returned when protected dynamic storage cannot be established and filled in place.
ProtectedSecretTextFillError: Error returned when protected UTF-8 storage cannot be established, filled, or validated.
ProtectionControl: Runtime control that failed during protected allocation.
ProtectionState: Actual outcome of one requested runtime protection.
Requirement: Whether a runtime memory-protection control is mandatory.
RollbackState: Result of one cleanup operation after failed construction.
SealedSecretAccessError: Error returned by scoped page-sealed secret access.
SecretAllocationError: Error returned when fallible dynamic secret allocation fails.
SecretGenerateError: Error returned by fallible dynamic secret generation.
SecretIntegrityError: Error returned by an operation that checks mapped-secret integrity.
SecretPoolGenerateError: Error returned when initializing a pool slot with a fallible generator.
SecretTextIntegrityError: Error returned when checked secret-text exposure detects corruption or invalid UTF-8.
SplitSecretError: Error returned by split-secret construction.

Constants§

DEFAULT_SECRET_STRING_SERDE_MAX_LEN: Default maximum accepted by serde deserialization into SecretString.
DEFAULT_SECRET_VEC_SERDE_MAX_LEN: Default maximum accepted by serde deserialization into SecretVec.

Traits§

DropSafeSanitize: Security contract for calling SecureSanitize from the value’s destructor.
MonotonicClock: Caller-provided monotonic tick source for no-std expiring secrets.
SecretIntegrityResultExt: Flattens a fallible mapped-secret exposure closure without losing the distinction between integrity corruption and the closure’s own error.
SecretStoragePolicy: Application-controlled allow-list for concrete secret storage types.
SecureSanitize: Clear the currently reachable sensitive contents owned by a value.
StableMutableSecretStorage: Security contract for secret storage exposed through mutable references.
StableSharedSecretStorage: Security contract for secret storage exposed through shared references.

Functions§

sanitize_then_abort: Sanitize one application-owned root value and then deliberately abort.
secure_replace: Sanitize a value before replacing it.

Type Aliases§

IntegrityResult: Result alias for mapped operations that can fail only because integrity canaries were corrupted.
LockedSecretBytesCheckedCopyError: Compatibility name for fixed-size copy operations that check integrity.
MappedResult: Result alias for mapped operations that distinguish integrity corruption from an operation-specific failure.
SecretBoxBytesBuildError: Compatibility name for fixed-allocation build failures.
SecretBoxBytesGenerateError: Compatibility name for fixed-allocation generation failures.
SecretIntegrityResult: Descriptive compatibility alias for MappedResult.

Derive Macros§

ConditionallySelectable: Derive sanitization::ct::ConditionallySelectable for structs.
ConstantTimeEq: Derive sanitization::ct::ConstantTimeEq for structs.
SecureSanitize: Derive sanitization::SecureSanitize for structs.
SecureSanitizeOnDrop: Derive Drop by invoking the complete SecureSanitize implementation.