secmem-alloc is a crate designed allocate private/secret memory. It is intended to be used for storing cryptographic secrets in memory. This crate provides custom allocators using various techniques to improve secrecy of the memory, most notably zeroization on deallocation.
For example, we read in a secret password from standard-in, which we want to zeroize on drop (deallocation). Note that this code does leave the password visible on the prompt; it is only to give an idea of how to use this crate.
```rust
// requires nightly_allocator_api crate feature to be enabled and a nightly compiler
use secmemalloc::allocatorapi::Allocator;
use secmemalloc::zeroizingalloc::ZeroizeAlloc;
use std::alloc::Global;
fn read_passwordbuf
}
fn main() { println!("Please enter your password: "); let mut stdin = std::io::stdin(); let allocator = ZeroizeAlloc::new(Global); let mut password = Vec::newin(allocator); readpassword(&mut password);
// use `password` however you like
// you can even grow and shrink the vector `password` and if it needs to be reallocated, the
// old allocation is immediately zeroized
// password is automatically zeroized on drop (deallocation)
} ```
As a second example assume you have a cryptographic secret key of 256 bytes, which should be zeroized on drop. In addition, we don’t want the key to be written to swap.
``rust
// requires no crate features and works on stable
// if you enable thenightlyallocatorapi` crate feature, the following line is necessary
use secmemalloc::allocatorapi::Allocator; use secmemalloc::boxed::Box; use secmemalloc::sec_alloc::SecStackSinglePageAlloc;
fn getsecretkeybuf with the bytes of the secret key
}
fn main() { let allocator: SecStackSinglePageAlloc = SecStackSinglePageAlloc::new().expect("could not create allocator"); let mut key = Box::newin([0u8; 256], &allocator); getsecretkey(&mut key);
// use `key` however you like
// `key` will not be written to swap except possibly on hibernation
// `key` is automatically zeroized on drop (deallocation)
} ```
std (default): Enable functionality that requires std. Currently only required for Error implements and required for tests. This feature is enabled by default.nightly_allocator_api (requires nightly): Use the nightly allocator api from the standard library (actually the core crate), gated behind the nightly-only feature allocator_api. When disabled, a copy of the allocator api included in this crate, available through secmem_alloc::allocator_api, will be used. This feature requires a nightly compiler.nightly_core_intrinsics (requires nightly): Use the intrinsics from the standard library (actually the core crate), gated behind the nightly-only feature core_intrinsics. This enables the extremely fast VolatileMemsetZeroizer zeroizer, and various other small optimisations. This feature requires a nightly compiler.nightly_stdsimd (requires nightly): Required for avx512 simd API in the standard libary, but currently unused. This feature requires a nightly compiler.nightly_strict_provenance (requires nightly): Enable strict provenance lints and (mostly) use strict provenance API provided by the standard library instead of the one from sptr. (Will still depend on and in a few places even use sptr.)nightly (requires nightly): Enable all nightly-only features (i.e. the above two). Enabling this feature is highly recommended when a nightly compiler is available. This feature requires a nightly compiler.dev (requires nightly): This feature enables all features required to run the test-suite, and should only be enabled for that purpose. This feature currently requires a nightly compiler.See CHANGELOG.md.
The API documentation of secmem-alloc is available at https://docs.rs/secmem-alloc/*/secmem_alloc/.