Struct SecretPool 

pub struct SecretPool<const N: usize, const SLOTS: usize> { /* private fields */ }

Fixed-slot arena for many same-size secrets inside one locked mapping.

SecretPool<N, SLOTS> amortizes platform memory-locking overhead when an application needs many fixed-size secrets at once. Instead of using one locked page-backed mapping per secret, the pool creates one private locked mapping large enough for SLOTS slots of N bytes and hands out lifetime-bound SecretPoolSlot handles.

Slots borrow the pool, so Rust prevents the pool from being dropped while a slot is still live. Dropping a slot volatile-clears exactly that slot and returns it to the pool. Dropping the pool volatile-clears the full mapping before unlocking and releasing it.

use sanitization::SecretPool;

let pool = SecretPool::<32, 4>::new().unwrap();
let slot = pool.try_allocate().unwrap().unwrap();
drop(pool); // rejected: `slot` still borrows the pool
drop(slot);

Implementations

impl<const N: usize, const SLOTS: usize> SecretPool<N, SLOTS>

pub fn new() -> Result<Self, MemoryLockError>

Create a locked pool with SLOTS fixed-size slots of N bytes.

This performs one platform mapping and one platform lock operation for the whole arena. The requested mapping length is rounded to the platform page granule, so the pool also clears padding bytes on drop.

pub fn new_hardened_native() -> Result<Self, ProtectionError>

Create a locked pool with the profile-hardened-native policy.

Preferred dump and fork exclusion outcomes remain visible through SecretPool::protection_report.

pub fn new_hardened_linux() -> Result<Self, ProtectionError>

Create a locked pool with the profile-hardened-linux policy.

pub fn new_with_protection( request: ProtectionRequest, ) -> Result<Self, ProtectionError>

Create a pool under an explicit runtime protection policy.

pub const fn slot_size(&self) -> usize

Number of bytes in each slot.

pub const fn capacity_slots(&self) -> usize

Number of slots in the pool.

pub const fn is_empty(&self) -> bool

Returns true when the pool cannot hold any secret bytes.

pub const fn locked_len(&self) -> usize

Rounded platform mapping length locked by this pool.

pub const fn protection_report(&self) -> &ProtectionReport

Actual runtime protections established for the pool mapping.

pub const fn protection_request(&self) -> ProtectionRequest

Runtime protection policy requested for the pool mapping.

pub const fn is_memory_locked(&self) -> bool

Returns true when the pool mapping is locked against ordinary paging.

pub fn available_slots(&self) -> usize

Count slots that are currently available.

This is a point-in-time observation. Other threads may allocate or release slots immediately after this method returns.

pub fn quarantined_slots(&self) -> usize

Count slots permanently withheld after an integrity failure.

This is public operational metadata. It does not expose mapping addresses, canary values, or secret bytes.

pub fn arena_report(&self) -> SecretPoolReport

Capture fixed-arena capacity, utilization, and lock-overhead metadata.

live_slots is a point-in-time observation. Other threads may allocate or release slots immediately after this method returns.

pub fn try_allocate( &self, ) -> Result<Option<SecretPoolSlot<'_, N, SLOTS>>, MemoryLockError>

Allocate one unused slot from the pool and report random-canary setup errors explicitly.

Ok(None) means only that every non-quarantined slot is in use. Random-canary setup failures are returned as MemoryLockError.

pub fn try_allocate_from_slice( &self, source: &[u8], ) -> Result<Option<SecretPoolSlot<'_, N, SLOTS>>, PoolInitError>

Allocate a slot and copy bytes from a same-length slice.

Returns Ok(None) when the pool is full. A length mismatch returns an error without allocating a slot.

pub fn try_allocate_from_array( &self, bytes: [u8; N], ) -> Result<Option<SecretPoolSlot<'_, N, SLOTS>>, PoolInitError>

Allocate a slot, copy an owned array into it, then clear this function’s owned array parameter. Other caller-retained copies are unaffected.

Ok(None) means only that the pool is exhausted. Platform setup and integrity failures remain distinct errors.

pub fn try_allocate_from_fn<E>( &self, make_byte: impl FnMut(usize) -> Result<u8, E>, ) -> Result<Option<SecretPoolSlot<'_, N, SLOTS>>, SecretPoolGenerateError<E>>

Allocate a slot and fallibly generate each byte directly inside it.

If generation fails, the partially initialized slot is volatile-cleared and returned to the pool before the error is returned.

pub fn secure_clear(&mut self)

Clear the full locked mapping and mark every slot available.

This requires &mut self, so Rust prevents it while any live slot handle still borrows the pool.

pub fn try_secure_clear_and_flush( &mut self, ) -> Result<CacheFlushReport, CacheFlushError>

Trait Implementations

impl<const N: usize, const SLOTS: usize> Debug for SecretPool<N, SLOTS>

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const N: usize, const SLOTS: usize> Drop for SecretPool<N, SLOTS>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<const N: usize, const SLOTS: usize> SecureSanitize for SecretPool<N, SLOTS>

fn secure_sanitize(&mut self)

Clear the sensitive bytes owned by this value.

impl<const N: usize, const SLOTS: usize> Send for SecretPool<N, SLOTS>

impl<const N: usize, const SLOTS: usize> StableMutableSecretStorage for SecretPool<N, SLOTS>

impl<const N: usize, const SLOTS: usize> StableSharedSecretStorage for SecretPool<N, SLOTS>

impl<const N: usize, const SLOTS: usize> Sync for SecretPool<N, SLOTS>