os-memlock

Quick links:

• Detailed guide: docs/overview.md
• API docs (docs.rs): https://docs.rs/os-memlock
• Examples:
  • examples/simple.rs
  • examples/locked_vec.rs

Docs

The detailed guide covers:

• Safety model and caller obligations: docs/overview.md#safety-model-and-caller-obligations
• Platform support and behavior: docs/overview.md#cross-platform-behavior
• Usage patterns and RAII wrappers: docs/overview.md#usage-patterns
• Error model and diagnostics: docs/overview.md#error-model
• Testing and CI: docs/overview.md#testing-and-ci
• Security considerations and threat model: docs/overview.md#security-considerations
• Integration checklist: docs/overview.md#integration-checklist

Small, focused crate providing thin, unsafe wrappers around OS memory-locking syscalls:

• mlock / munlock (prevent swapping)
• madvise_dontdump (best-effort exclusion from core dumps: Linux MADV_DONTDUMP, FreeBSD MADV_NOCORE)

This crate isolates the minimal unsafe FFI surface so higher-level modules can remain #![forbid(unsafe_code)]. The public functions are intentionally unsafe to make pointer-safety obligations explicit to callers.

Purpose

• Provide a tiny, audit-friendly layer over platform syscalls used to lock memory pages and apply dump-exclusion hints.
• Keep all unsafe and FFI details in a single, well-documented crate so the rest of the codebase can use a safe abstraction that validates inputs before calling into this crate when appropriate.
• Expose a stable, minimal API that is easy to reason about and to wrap in safer helpers.

Crate API (surface)

The crate re-exports the platform-specific implementations at the crate root:

• unsafe fn mlock(addr: *const std::os::raw::c_void, len: usize) -> std::io::Result<()>

  • Lock the pages containing the memory region so they are not swapped out.
  • On unsupported platforms, returns Err(io::ErrorKind::Unsupported).

• unsafe fn munlock(addr: *const std::os::raw::c_void, len: usize) -> std::io::Result<()>

  • Unlock the pages, reversing mlock.
  • On unsupported platforms, returns Err(io::ErrorKind::Unsupported).

• unsafe fn madvise_dontdump(addr: *mut std::os::raw::c_void, len: usize) -> std::io::Result<()>

  • Best-effort hint to exclude a mapping from core dumps (Linux: MADV_DONTDUMP, FreeBSD: MADV_NOCORE).
  • On unsupported platforms, returns Err(io::ErrorKind::Unsupported).

Notes on signatures:

• The functions intentionally use raw pointers and usize lengths to mirror the OS call semantics and to avoid hiding important safety obligations behind false safety.
• Zero-length regions are treated as a no-op and return Ok(()) for ergonomic callers.

Safety contract

All functions are unsafe. Callers must uphold the following preconditions for each call:

1. The (addr, len) pair must denote a valid memory region that the caller owns for the duration of the call and for as long as the OS considers the lock to be held.

   • The range must be mapped into the process address space and addressable (initialized) memory. Passing invalid pointers is undefined behavior at the OS/FFI boundary.

2. The memory region must not be concurrently deallocated, unmapped, or remapped while the system call is in-flight. Concurrent unmapping or reallocation may cause the OS call to operate on a different mapping and can lead to undefined behavior or kernel errors.

3. Callers must ensure alignment and fractional-page concerns are addressed if required by their higher-level policy; the OS operates at page granularity, but mlock is defined on an arbitrary address and length.

4. When using mlock to protect secrets, callers must consider:

   • Handling and limiting locked memory lifetime.
   • Zeroizing secrets before munlock/drop, where appropriate.
   • Observability: mlock failures may be transient or platform-dependent — be prepared to treat Err(Unsupported) and other error kinds as operational signals.

5. For madvise_dontdump:

   • This is advisory and best-effort; the kernel may ignore or reject the hint.
   • Use it as a privacy/operational enhancement, not a strict security boundary.

Platform support & behavior

• Unix (Linux, *BSD, macOS):

  • mlock and munlock call through to libc::mlock and libc::munlock.
  • madvise_dontdump:
    • On Linux: wraps madvise(..., MADV_DONTDUMP).
    • On FreeBSD: wraps madvise(..., MADV_NOCORE).
    • On macOS and other Unix targets: returns Err(io::ErrorKind::Unsupported).

• Non-Unix platforms:

  • All functions return Err(io::ErrorKind::Unsupported).
  • The function signatures exist to preserve a consistent cross-platform API; callers should handle Unsupported gracefully.

Examples (usage guidance)

• Minimal unsafe call (illustrative — not a full safety wrapper):

Use mlock to lock a buffer you control. Wrap calls in unsafe and uphold the safety contract:

unsafe { os_memlock::mlock(buf.as_ptr() as *const _, buf.len())?; }

Later, before drop/unmapping: unsafe { os_memlock::munlock(buf.as_ptr() as *const _, buf.len())?; }

Call madvise_dontdump on Linux/FreeBSD to reduce chance of core dump exposure: unsafe { os_memlock::madvise_dontdump(buf.as_mut_ptr() as *mut _, buf.len())?; }

• Higher-level recommended pattern:
  • Prefer a safe wrapper in your application that:
    • Accepts owned buffers (e.g., a wrapper type),
    • Ensures the buffer lives for the duration of the lock,
    • Calls mlock at allocation or when the secret is installed,
    • Zeroizes the content before munlock and ensures munlock is called (via Drop).
  • See src/mem/locked.rs in this repository for an example of a safe LockedVec style wrapper.

Error handling and diagnostics

• io::ErrorKind::Unsupported signals platform/build-time unavailability; do not treat it as a panic-worthy error unless your feature policy requires it.
• Other OS errors (e.g., resource limits) will be returned as io::Error with kernel errno translated into std::io::Error. These must be handled by the caller or propagated with context.

Testing notes

• Unit tests in the repository provide behavior verification in environments where syscalls are available. Tests exercise both success paths and fallback behavior.
• Where platform syscalls are unavailable or require elevated privileges, tests should mock or stub the syscall provider rather than invoking real FFI.

macOS process-wide core-dump helper

macOS does not expose a per-region dump-exclusion advice via madvise (there is no MADV_DONTDUMP/MADV_NOCORE on Darwin). To offer a practical alternative, this crate provides opt-in, process-wide helpers:

• disable_core_dumps_for_process():

  • Platform: macOS-only behavior; on other platforms this function returns io::ErrorKind::Unsupported.
  • Effect: Sets the process RLIMIT_CORE soft limit to 0 to disable generation of core dumps for the process.
  • Safety: Exposed as a safe function because it has no pointer/lifetime obligations; it returns io::Result<()> on failure/success.
  • Scope: Process-wide and inherited by child processes. This is not a per-buffer or per-region setting.
  • Privileges: Lowering the soft limit to 0 is typically permitted; raising limits back may require additional privileges or be disallowed by system policy.
  • Operational notes: In sandboxed or restricted environments, changing resource limits may fail. Handle errors and decide whether to degrade gracefully or fail closed, per your policy.

• disable_core_dumps_with_guard() -> CoreDumpsDisabledGuard:

  • Platform: macOS-only; on other platforms this function returns io::ErrorKind::Unsupported.
  • Effect: Sets the process RLIMIT_CORE soft limit to 0 and returns a guard. When the guard is dropped, the previous limits are restored for the current process.
  • Scope: Process-wide while active. Child processes forked while disabled inherit the lowered limit and are not automatically “restored” by dropping the guard in the parent.
  • Safety: Safe API returning io::Result<CoreDumpsDisabledGuard>.
  • Privileges & operational notes: Same as above; restoration may fail under restrictive policies (restoration errors are best-effort and should be logged by callers if needed).

Recommended usage:

• For temporary disabling (e.g., during sensitive operations), prefer disable_core_dumps_with_guard() to ensure restoration even on panic or early returns.
• For a whole-process policy, call disable_core_dumps_for_process() early in startup.
• Combine with mlock/munlock to reduce the risk of secrets being paged to disk.
• Log or surface metrics if the helper is unsupported or fails, so you can detect drift from your intended security posture.

Windows process-wide error-dialog helpers

Windows does not provide a per-region dump-exclusion API analogous to MADV_DONTDUMP. To improve operational behavior (avoiding certain error UI), this crate provides opt-in, process-wide helpers:

• set_windows_error_mode(new_mode: u32) -> io::Result<u32>:

  • Platform: Windows-only; on other platforms returns io::ErrorKind::Unsupported.
  • Effect: Calls SetErrorMode with the provided flags and returns the previous mode.
  • Scope: Process-wide; inherited by child processes created after the change.
  • Notes: This does not control crash dump contents and is not a security feature. It primarily suppresses certain error dialogs.

• suppress_windows_error_dialogs_for_process() -> io::Result<u32>:

  • Platform: Windows-only; on other platforms returns io::ErrorKind::Unsupported.
  • Effect: Applies a common combination of flags (SEM_FAILCRITICALERRORS | SEM_NOGPFAULTERRORBOX | SEM_NOOPENFILEERRORBOX) via SetErrorMode and returns the previous mode.
  • Scope: Process-wide; inherited by child processes created after the change.
  • Notes: This is best-effort UX/operational control and is not equivalent to per-region dump exclusion.

Recommended usage:

• Call early in process startup if you want to suppress Windows error dialogs globally.
• Save and restore the previous mode when temporarily changing settings to limit blast radius.
• Treat these helpers as operational/UX tweaks, not security controls; combine with mlock/munlock for memory handling as needed.

License

This crate is dual-licensed under Apache-2.0 OR MIT; see Cargo.toml for details.