Skip to content

Commit 4080101

Browse files
committed
first commit
0 parents  commit 4080101

1 file changed

Lines changed: 74 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# sanitization
2+
3+
Dependency-free `no_std` secret memory sanitization for Rust.
4+
5+
Default builds use `#![forbid(unsafe_code)]`. The intended path is to store new
6+
fixed-size secrets in `SecretBytes<N>` from creation, avoiding accidental
7+
`Copy`, `Clone`, slice exposure, and secret-printing `Debug`.
8+
9+
With the `alloc` feature, dynamic heap secrets are available through
10+
`SecretVec` and `SecretString`. These types wipe on drop and expose contents
11+
through closure-based APIs.
12+
13+
For integration boundaries that must wipe ordinary buffers, enable the explicit
14+
unsafe-backed feature:
15+
16+
```bash
17+
cargo test --features unsafe-wipe
18+
```
19+
20+
Then call APIs under `sanitization::unsafe_wipe`, such as
21+
`unsafe_wipe::volatile_sanitize_bytes(&mut bytes)`. Enabling the feature does
22+
not change the default `SecureSanitize` implementation for ordinary `[u8]`;
23+
call sites must opt into the volatile backend by name.
24+
25+
## Examples
26+
27+
```rust
28+
use sanitization::SecretBytes;
29+
30+
let key = SecretBytes::<32>::from_fn(|index| index as u8);
31+
let ok = key.expose_secret(|bytes| bytes.len() == 32);
32+
assert!(ok);
33+
```
34+
35+
```rust
36+
#[cfg(feature = "alloc")]
37+
use sanitization::SecretVec;
38+
39+
#[cfg(feature = "alloc")]
40+
let token = SecretVec::from_slice(b"bearer-token");
41+
```
42+
43+
```rust
44+
#[cfg(feature = "unsafe-wipe")]
45+
{
46+
let mut bytes = [0xA5; 32];
47+
sanitization::unsafe_wipe::volatile_sanitize_bytes(&mut bytes);
48+
}
49+
```
50+
51+
## Feature Matrix
52+
53+
- `default`: `no_std`, no external dependencies, no unsafe code.
54+
- `alloc`: adds `SecretVec` and `SecretString`.
55+
- `std`: currently aliases `alloc` for downstream convenience.
56+
- `unsafe-wipe`: exposes the explicit volatile-write backend.
57+
58+
## Checks
59+
60+
Run the local matrix before changing release-sensitive code:
61+
62+
```bash
63+
bash scripts/checks.sh
64+
```
65+
66+
See `THREAT_MODEL.md` and `SAFETY.md` before extending the unsafe backend.
67+
68+
## Limits
69+
70+
- Safe Rust cannot volatile-wipe arbitrary existing memory.
71+
- Safe Rust cannot soundly scrub old stack frames from previous moves.
72+
- CPU cache flushes, SIMD clearing, platform memory locking, and inline
73+
assembly require more target-specific unsafe code and are intentionally not
74+
part of the default API.

0 commit comments

Comments
 (0)