Skip to main content

Crate shrouded

Crate shrouded 

Source
Expand description

§Shroud

Secure memory management with mlock, guard pages, and automatic zeroization.

shrouded provides types for storing secrets in protected memory that is:

  • Locked to RAM (mlock/VirtualLock) to prevent swapping to disk
  • Guard-paged to catch buffer overflows/underflows
  • Excluded from core dumps (MADV_DONTDUMP on Linux)
  • Automatically zeroized on drop using volatile writes

§Quick Start

use shrouded::{ShroudedString, Expose};

// Create a protected secret from a String (original is zeroized)
let password = String::from("hunter2");
let secret = ShroudedString::new(password).unwrap();

// Access the secret when needed
assert_eq!(secret.expose(), "hunter2");

// Secret is automatically zeroized when dropped

§Types

§Policy

Control how memory protection failures are handled with Policy:

  • BestEffort (default): Attempt protection, fall back gracefully
  • Strict: Require all protection to succeed, error on failure
  • Disabled: Skip protection (still zeroizes on drop)
use shrouded::{ShroudBuilder, Policy};

let mut key = [0x42u8; 32];
let secret = ShroudBuilder::new()
    .policy(Policy::Strict)
    .build_bytes(&mut key)
    .unwrap();

§Features

  • mlock (default): Enable memory locking
  • guard-pages (default): Enable guard pages
  • serde: Enable deserialize support (never serialize!)

§Security Considerations

  • Secrets are protected from being swapped to disk
  • Guard pages help detect buffer overflows
  • Debug output shows [REDACTED] instead of secret data
  • No Display impl - must explicitly call .expose()
  • No Clone impl - must explicitly call .try_clone()
  • Serde only implements Deserialize, never Serialize

Structs§

ExposeGuard
A guard that provides temporary access to protected memory.
ExposeGuardMut
A mutable guard that provides temporary write access to protected memory.
Shroud
A generic protected box for any type implementing Zeroize.
ShroudBuilder
A builder for creating shrouded types with custom configuration.
ShroudedArray
A fixed-size protected byte array.
ShroudedBytes
A dynamic-size protected byte buffer.
ShroudedString
A UTF-8 string stored in protected memory.

Enums§

Policy
Policy controlling how memory protection failures are handled.
ShroudError
Errors that can occur during protected memory operations.

Traits§

Expose
Trait for types that can expose their protected contents as an immutable reference.
ExposeGuarded
Trait for types that support guarded access with automatic re-locking.
ExposeGuardedMut
Trait for types that support mutable guarded access with automatic re-locking.
ExposeMut
Trait for types that can expose their protected contents as a mutable reference.
Zeroize
Trait for securely erasing values from memory.

Type Aliases§

Result
Result type alias for shrouded operations.

Derive Macros§

Zeroize
Derive the Zeroize trait.