1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
//! [`Allocator`](std::alloc::Allocator) type that allocates memory using
//! [Sodium](https://doc.libsodium.org/)'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`](https://doc.libsodium.org/memory_management#guarded-heap-allocations) 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`](https://doc.libsodium.org/memory_management#locking-memory) 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);
//! ```
#![doc(html_root_url = "https://docs.rs/sodium-alloc/0.1.1")]
#![feature(allocator_api)]
#![feature(nonnull_slice_from_raw_parts)]
#![feature(slice_ptr_get)]
#![feature(slice_ptr_len)]
use libsodium_sys as sodium;
use std::alloc::{AllocError, Allocator, Layout};
use std::ffi::c_void;
use std::ptr::NonNull;
/// An [`Allocator`](std::alloc::Allocator) which allocates and frees memory using Sodium's secure
/// memory utilities.
///
/// Allocation of memory using this struct is expensive - it shouldn't be used as a global
/// allocator, but rather confied to manage memory for data structures storing sensitive
/// information, such as keys, passwords, etc.
///
/// When this Allocator frees memory, it is securely zeroed, so there is no need to implement
/// Zeroize or similar constructions for types with memory managed via this struct.
///
/// If the canary Sodium places before the allocated memory is altered, or if an attempt to access
/// a guard page surrounding the allocated memory is made, the program will automatically
/// terminate. This behaviour should never occur in safe Rust.
#[derive(Copy, Clone, Debug)]
pub struct SodiumAllocator;
unsafe impl Allocator for SodiumAllocator {
fn allocate(&self, mut layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
// Initialise libsodium, okay to call this multiple times from multiple threads, the actual
// initialisation will only happen once.
// We don't call this in other functions, as it's assumed we have to have called
// `Self::allocate` to get some memory to do other things with (e.g: deallocate, grow).
init()?;
// Increase the size of the layout so it's a multiple of layout.align - as Sodium allocates
// memory at the end of the page, as long as the layout size is a multiple of the
// alignment, and the alignment is a power of 2, the allocation will be correctly aligned.
layout = layout.pad_to_align();
// Calling `sodium_malloc` with a size that's a multiple of n produces a pointer aligned to
// n.
// SAFETY: This function returns a pointer to `layout.size()` of allocated memory, or NULL
// if allocation failed. We immediately check for NULL in the next line, and return an
// error if it occurs. If the result is not NULL, Sodium guarantees that the pointer will
// reference at least `layout.size()` of allocated, mutable memory.
let ptr = unsafe { sodium::sodium_malloc(layout.size()) as *mut u8 };
// NonNull::new() will return Some if `ptr` was non-null, but will return None if `ptr` was
// null. We convert the latter result into an error.
let ptr = NonNull::new(ptr).ok_or(AllocError)?;
Ok(NonNull::slice_from_raw_parts(ptr, layout.size()))
}
unsafe fn deallocate(&self, ptr: NonNull<u8>, _layout: Layout) {
sodium::sodium_free(ptr.as_ptr() as *mut c_void);
}
// We just use the default implementations of the other methods: Sodium doesn't provide any API
// to grow/shrink memory, so we would have to just allocate new memory then copy for any of
// these types of operations, which is what the default operations already do.
}
/// Initialise libsodium.
///
/// Called automatically when an attempt to allocate is made.
fn init() -> Result<(), AllocError> {
unsafe {
if sodium::sodium_init() >= 0 {
Ok(())
} else {
Err(AllocError)
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::alloc::Layout;
use std::error::Error;
#[test]
fn basic_allocation() -> Result<(), Box<dyn Error>> {
// Tries to allocate up to 0.5GiB
for i in 0..29 {
let layout = Layout::from_size_align(1 << i, 1)?;
let ptr = SodiumAllocator.allocate(layout)?;
assert_eq!(ptr.len(), 1 << i);
unsafe {
SodiumAllocator.deallocate(ptr.cast(), layout);
}
}
Ok(())
}
#[test]
fn alignment_correct() -> Result<(), Box<dyn Error>> {
// Test some repeated allocations, ensure that they're always aligned correctly
for _ in 0..100 {
let layout_a = Layout::from_size_align(13, 4)?;
let ptr_a = SodiumAllocator.allocate(layout_a)?;
assert_eq!(ptr_a.as_ptr() as *mut () as u8 % 4, 0);
let layout_b = Layout::from_size_align(12, 4)?;
let ptr_b = SodiumAllocator.allocate(layout_b)?;
assert_eq!(ptr_b.as_ptr() as *mut () as u8 % 4, 0);
let layout_c = Layout::from_size_align(20, 16)?;
let ptr_c = SodiumAllocator.allocate(layout_c)?;
assert_eq!(ptr_c.as_ptr() as *mut () as u8 % 16, 0);
unsafe {
SodiumAllocator.deallocate(ptr_a.cast(), layout_a);
SodiumAllocator.deallocate(ptr_b.cast(), layout_b);
SodiumAllocator.deallocate(ptr_c.cast(), layout_c);
}
}
Ok(())
}
#[test]
fn zero_size_alloc() -> Result<(), Box<dyn Error>> {
let layout = Layout::from_size_align(0, 1)?;
let ptr = SodiumAllocator.allocate(layout)?;
assert_eq!(ptr.len(), 0);
unsafe {
SodiumAllocator.deallocate(ptr.cast(), layout);
}
Ok(())
}
#[test]
fn test_writing() {
for i in 0..29 {
let mut v: Vec<u8, _> = Vec::with_capacity_in(1 << i, SodiumAllocator);
for _ in 0..(1 << i) {
v.push(0x13);
}
}
}
}