Crate sodium_alloc

Allocator type that allocates memory using Sodium’s secure memory utilities.

Requires nightly Rust, as the Allocator API is not yet stable.

This library implements SodiumAllocator, an Allocator which uses the sodium_malloc and corresponding sodium_free functions to manage memory. When managing sensitive data in memory, there are a number of steps we can take to help harden our software against revealing these secrets.

Sodium’s sodium_malloc implementation introduces many of these hardening steps to the memory management process: Allocated memory is placed at the end of a page boundary, immediately followed by a guard page (a region of memory which is marked as inaccessible, any attempt to access it will result in termination of the program). A canary is placed before the allocated memory, any modifications to which are detected on free, again resulting in program termination, and a guard page is placed before this. sodium_mlock is used to instruct the operating system not to swap the memory to disk, or to include it in core dumps.

When memory is freed with SodiumAllocator, the sodium_free function is called, which will securely zero the memory before marking it as free. This means that for types allocated with SodiumAllocator, there is no need to implement Zeroize or a similar Drop implementation to zero the memory when no longer in use: It will automatically be zeroed when freed.

This library is not suitable for use as a general-purpose allocator or global allocator: The overhead of this API is much greater than Rust’s standard allocator, and the implementation is more likely to encounter errors. It is intended for use when allocating sensitive data types only, for example, a key or password which needs to be stored in memory.

Examples

Here we create a standard Rust vector, but use Sodium’s memory management to allocate/grow/free its memory:

// Currently necessary: Allocators are feature-gated on nightly
#![feature(allocator_api)]

use std::alloc::Allocator;
use sodium_alloc::SodiumAllocator;

// Allocate a vector using Sodium's memory management functions
let mut my_vec = Vec::with_capacity_in(4, SodiumAllocator);
my_vec.push(0);
my_vec.push(1);
my_vec.extend_from_slice(&[3, 4]);
println!("{:?}", my_vec);
// Grow the vector, works just like normal :)
my_vec.reserve(10);
// Drop the vector, the SodiumAllocator will securely zero the memory when freed. Dropping like
// this isn't necessary, things going out of scope as normal works too, this is just for
// illustrative purposes.
std::mem::drop(my_vec);

Boxes also currently support the Allocator API:

#![feature(allocator_api)]

use std::alloc::Allocator;
use sodium_alloc::SodiumAllocator;

// Store something on the heap, allocating memory with Sodium
let key = Box::new_in([0xca, 0xfe, 0xba, 0xbe], SodiumAllocator);
println!("{:x?}", key);

Structs

SodiumAllocator

An Allocator which allocates and frees memory using Sodium’s secure memory utilities.