Repository files navigation

secmem-alloc is a crate designed allocate private/secret memory. It isintended to be used for storing cryptographic secrets in memory. This crateprovides custom allocators using various techniques to improve secrecy ofthe memory, most notably zeroization on deallocation.

For example, we read in a secret password from standard-in, which we want tozeroize on drop (deallocation). Note that this code does leave the passwordvisible on the prompt; it is only to give an idea of how to use this crate.

#![feature(allocator_api)]// requires `nightly_allocator_api` crate feature to be enabled and a nightly compileruse secmem_alloc::allocator_api::{Allocator,Global,Vec};use secmem_alloc::zeroizing_alloc::ZeroizeAlloc;fnread_password<A:Allocator>(buf:&mutVec<u8,A>){// query password from the user and put it in `buf`}fnmain(){println!("Please enter your password: ");letmut stdin = std::io::stdin();let allocator =ZeroizeAlloc::new(Global);letmut password =Vec::new_in(allocator);read_password(&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 bewritten to swap.

// requires no crate features and works on stable// if you enable the `nightly_allocator_api` crate feature, the following line is necessary#![feature(allocator_api)]use secmem_alloc::allocator_api::{Allocator,Box};use secmem_alloc::sec_alloc::SecStackSinglePageAlloc;fnget_secret_key<A:Allocator>(buf:&mutBox<[u8;256],A>){// fill `buf` with the bytes of the secret key}fnmain(){let allocator:SecStackSinglePageAlloc =SecStackSinglePageAlloc::new().expect("could not create allocator");letmut key =Box::new_in([0_u8;256],&allocator);get_secret_key(&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 requiresstd. Currently onlyrequired forError implements and required for tests. This feature isenabled by default.
• nightly_allocator_api (requires nightly): Use the nightly allocator apifrom the standard library (actually thecore crate), gated behind thenightly-only featureallocator_api. When disabled, a copy of theallocator api included in this crate, available throughsecmem_alloc::allocator_api, will be used. This feature requires anightly compiler.
• nightly_core_intrinsics (requires nightly): Use the intrinsics from thestandard library (actually thecore crate), gated behind thenightly-only featurecore_intrinsics. This allows for a slightly fasterzeroize_mem implementation, and various other small optimisations.This feature requires a nightly compiler.
• nightly (requires nightly): Enable all nightly-only features (i.e. theabove two). Enabling this feature is highly recommended when a nightlycompiler is available. This feature requires a nightly compiler.
• dev (requires nightly): This feature enables all features required torun the test-suite, and should only be enabled for that purpose. Thisfeature currently requires a nightly compiler.

Since this crate still depends on several nightly features for optimalfunctioning, the MSRV is expected to track the latest stable relativelyclosely. Therefore, we might bump the MSRV in patch version bumps. Thisshouldn’t be an issue given the new MSRV aware dependency resolver incargo. This policy might change as more unstable features get stabilised.