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).