Module dryoc::protected

Available on crate feature nightly only.

Memory protection utilities

Provides access to the memory locking system calls, such as mlock() and mprotect() on UNIX-like systems, VirtualLock() and VirtualProtect() on Windows. Similar to libsodium’s sodium_mlock and sodium_mprotect_* functions.

On Linux, sets MADV_DONTDUMP with madvise() on locked regions.

The protected memory features leverage Rust’s Allocator API, which requires nightly Rust. This crate must be built with the nightly feature flag enabled to activate these features.

For details on the Allocator API, see: https://github.com/rust-lang/rust/issues/32838

If the serde feature is enabled, the serde::Deserialize and serde::Serialize traits will be implemented for HeapBytes and HeapByteArray.

Example

use dryoc::protected::*;

// Create a read-only, locked region of memory
let readonly_locked = HeapBytes::from_slice_into_readonly_locked(b"some locked bytes")
    .expect("failed to get locked bytes");

// ... now do stuff with `readonly_locked` ...
println!("{:?}", readonly_locked.as_slice());

Protection features

The type safe API uses traits to guard against misuse of protected memory. For example, memory that is set as read-only can be accessed with immutable accessors (such as .as_slice() or .as_array()), but not with mutable accessors like .as_mut_slice() or .as_mut_array().

use dryoc::protected::*;

// Create a read-only, locked region of memory
let readonly_locked = HeapBytes::from_slice_into_readonly_locked(b"some locked bytes")
    .expect("failed to get locked bytes");

// Try to access the memory mutably
println!("{:?}", readonly_locked.as_mut_slice()); // fails to compile, cannot access mutably

Memory that has been protected as read-only or no-access will cause the process to crash if you attempt to access the memory improperly. To test this, try the following code (which requires an unsafe block):

use dryoc::protected::*;

// Create a read-only, locked region of memory
let readonly_locked = HeapBytes::from_slice_into_readonly_locked(b"some locked bytes")
    .expect("failed to get locked bytes");

// Write to a protected region of memory, causing a crash.
unsafe {
    std::ptr::write(readonly_locked.as_slice().as_ptr() as *mut u8, 0) // <- crash happens here
};

Running the code above produces as signal: 10, SIGBUS: access to undefined memory panic.

Re-exports

pub use crate::types::*;

pub use ptypes::*;

Modules

ptypes

Short-hand type aliases for protected types.

Structs

HeapByteArray

A heap-allocated fixed-length byte array, using the page-aligned allocator. Required for working with protected memory regions. Wraps a Vec with custom Allocator implementation.

HeapBytes

A heap-allocated resizable byte array, using the page-aligned allocator. Required for working with protected memory regions. Wraps a Vec with custom Allocator implementation.

PageAlignedAllocator

Custom page-aligned allocator implementation. Creates blocks of page-aligned heap-allocated memory regions, with no-access pages before and after the allocated region of memory.

Protected

Holds Protected region of memory. Does not implement traits such as Copy, Clone, or std::fmt::Debug.

Traits

Lock

Protected region of memory that can be locked.

Lockable

A region of memory that can be locked, but is not yet protected. In order to lock the memory, it may require making a copy.

NewLocked

Bytes which can be allocated and protected.

NewLockedFromSlice

Create a new region of protected memory from a slice.

ProtectNoAccess

Protected region of memory that can be set as no-access. Must be unlocked.

ProtectReadOnly

Protected region of memory that can be set as read-only.

ProtectReadWrite

Protected region of memory that can be set as read-write.

Unlock

Protected region of memory that can be locked (i.e., is already locked).