Enum LockPolicy 

pub enum LockPolicy {
    BestEffort,
    Strict,
}

What a Locked constructor does when the operating system refuses to lock the memory or, on Linux, to exclude it from core dumps.

The policy is process-wide and set at most once, with LockPolicy::set. Until it is set, BestEffort applies.

Which to choose

A refused lock loses exactly one property: under memory pressure the pages holding the secret may be written to swap, which is not wiped when the process exits. On a host with no swap there is nothing to lose. Everything else, including the wipe on drop and the exclusion from core dumps on Linux, still holds. A refused dump exclusion, which is rare and takes a seccomp filter to provoke, is treated the same way.

BestEffort is the default because a strict default fails in development and CI, where swap exposure is irrelevant, and teaches people to turn it off. A service that needs the guarantee sets Strict once at startup, or checks Locked::locked on the values it cares about.

Variants

BestEffort

Create the value anyway and record the refusal, readable from Locked::lock_error. When more than one protection is refused, the lock refusal is the one recorded.

Strict

Fail the constructor with the refusal. Where locking is unavailable altogether (non-Unix targets, Miri, Kani) that is every constructor: LockError::Unavailable is a refusal too.

Implementations

impl LockPolicy

pub fn set(self) -> Result<(), LockPolicyError>

Set the process-wide policy. Succeeds at most once, or again with the same value; a different value after the first is an error carrying the policy in force.

use vitaminc::protected::LockPolicy;

// A test binary runs many tests in one process; set once, tolerate repeats.
let _ = LockPolicy::BestEffort.set();
assert_eq!(LockPolicy::current(), LockPolicy::BestEffort);

pub fn current() -> Self

The policy in force: the one set with set, or BestEffort.

Trait Implementations

impl Clone for LockPolicy

fn clone(&self) -> LockPolicy

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for LockPolicy

impl Debug for LockPolicy

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

Formats the value using the given formatter.

impl Default for LockPolicy

fn default() -> LockPolicy

Returns the “default value” for a type.

impl Eq for LockPolicy

impl PartialEq for LockPolicy

fn eq(&self, other: &LockPolicy) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for LockPolicy