Struct GuardedSecretVec 

pub struct GuardedSecretVec { /* private fields */ }

Dynamic secret bytes stored between inaccessible platform guard pages.

This type is available with the guard-pages feature on supported Linux, Android, macOS, iOS, Windows, and BSD targets. Secret bytes live in private platform mappings. The pages immediately before and after the writable data region remain inaccessible, so linear overreads or overwrites past the mapped data region fault instead of reaching unrelated memory.

The secret bytes are not allocated with the Rust global allocator.

Implementations

impl GuardedSecretVec

pub fn with_capacity(capacity: usize) -> Result<Self, GuardPageError>

Create an empty guarded secret buffer with at least capacity bytes of writable data space.

pub fn with_capacity_guarded_native( capacity: usize, ) -> Result<Self, ProtectionError>

Create guarded storage with the profile-guarded-native policy.

Guard pages, memory locking, and canaries are required. Preferred dump and fork exclusion outcomes remain visible through GuardedSecretVec::protection_report.

pub fn locked_with_capacity(capacity: usize) -> Result<Self, GuardPageError>

Create an empty guarded secret buffer and lock its writable data pages with the platform memory-locking backend.

This constructor is available when both guard-pages and memory-lock are enabled. Locking can fail due to operating-system resource limits or policy. Core-dump and fork-inheritance exclusion can fail if the kernel rejects the requested madvise policies. On failure, the mapping is unmapped before the error is returned. Guard pages are not locked because they never contain secret bytes.

pub fn with_capacity_with_protection( capacity: usize, request: ProtectionRequest, ) -> Result<Self, ProtectionError>

Create guarded storage under an explicit runtime protection policy.

Guard pages are intrinsic to this type and are always required. Preferred lock, dump, or fork controls may fail while construction succeeds with an explicit reduced-protection report.

pub fn from_slice_with_protection( bytes: &[u8], request: ProtectionRequest, ) -> Result<Self, ProtectedSecretFillError<Infallible>>

Create guarded dynamic storage by copying a slice only after all required controls have been established.

Guard pages are intrinsic and required. Mark memory locking, dump exclusion, fork policy, canaries, or other controls Requirement::Required when they must also precede secret materialization.

pub fn from_fn_with_protection( len: usize, request: ProtectionRequest, make_byte: impl FnMut(usize) -> u8, ) -> Result<Self, ProtectedSecretFillError<Infallible>>

Generate bytes directly into guarded dynamic storage after all required controls have been established.

pub fn try_from_fn_with_protection<E>( len: usize, request: ProtectionRequest, make_byte: impl FnMut(usize) -> Result<u8, E>, ) -> Result<Self, ProtectedSecretFillError<E>>

Fallibly generate bytes directly into guarded dynamic storage after all required controls have been established.

pub fn from_exact_len_with_protection( len: usize, request: ProtectionRequest, fill: impl FnOnce(&mut [u8]), ) -> Result<Self, ProtectedSecretFillError<Infallible>>

Fill an exact-length guarded payload only after all required controls have been established.

If fill panics, clear-on-drop ownership remains active for the entire writable mapping during unwinding.

pub fn try_from_exact_len_with_protection<E>( len: usize, request: ProtectionRequest, fill: impl FnOnce(&mut [u8]) -> Result<(), E>, ) -> Result<Self, ProtectedSecretFillError<E>>

Fallible variant of GuardedSecretVec::from_exact_len_with_protection.

The fill closure is never invoked when a required control fails. A fill error clears the complete writable mapping before returning.

pub fn from_capacity_with_protection( capacity: usize, request: ProtectionRequest, fill: impl FnOnce(&mut [u8]) -> usize, ) -> Result<Self, ProtectedSecretFillError<Infallible>>

Fill guarded dynamic storage and return the initialized byte length.

This is the infallible-fill counterpart of GuardedSecretVec::try_from_capacity_with_protection.

pub fn try_from_capacity_bounded_with_protection<E>( capacity: usize, maximum: usize, request: ProtectionRequest, fill: impl FnOnce(&mut [u8]) -> Result<usize, E>, ) -> Result<Self, ProtectedSecretFillError<E>>

Bounded variant of GuardedSecretVec::try_from_capacity_with_protection.

Use this constructor whenever capacity originates from an untrusted protocol length, decoder hint, or message field. A capacity above maximum is rejected before mapping, protection setup, or invoking fill.

pub fn try_from_capacity_with_protection<E>( capacity: usize, request: ProtectionRequest, fill: impl FnOnce(&mut [u8]) -> Result<usize, E>, ) -> Result<Self, ProtectedSecretFillError<E>>

Fill guarded dynamic storage only after all required controls have been established.

This unbounded constructor supports trusted capacities that the application has already limited. Use GuardedSecretVec::try_from_capacity_bounded_with_protection at untrusted protocol boundaries. No plaintext is materialized before mandatory guard, lock, dump, fork, or canary controls succeed. The closure is not invoked when any Requirement::Required control fails. Controls marked Requirement::Preferred retain their normal degraded-success semantics and remain visible through GuardedSecretVec::protection_report.

If fill fails or reports more than capacity initialized bytes, the complete writable mapping is cleared before the error is returned. Unused tail bytes are also cleared before successful construction.

pub fn from_slice(bytes: &[u8]) -> Result<Self, GuardPageError>

Create a guarded secret buffer by copying bytes from a slice.

pub fn from_fn( len: usize, make_byte: impl FnMut(usize) -> u8, ) -> Result<Self, GuardPageError>

Create a guarded secret buffer by writing generated bytes directly into the guarded mapping.

This avoids staging dynamically generated secret bytes in an ordinary intermediate allocation before they enter guarded storage.

pub fn try_from_fn<E>( len: usize, make_byte: impl FnMut(usize) -> Result<u8, E>, ) -> Result<Self, GuardedSecretVecGenerateError<E>>

Create a guarded secret buffer by fallibly writing generated bytes directly into the guarded mapping.

If generation fails, any bytes already written into the guarded mapping are cleared before the error is returned.

pub fn locked_from_slice(bytes: &[u8]) -> Result<Self, GuardPageError>

Create a guarded and memory-locked secret buffer by copying bytes from a slice.

The writable data pages are locked before bytes are copied into them. OS-specific dump or fork-exclusion policies are applied where the backend supports them.

pub fn locked_from_fn( len: usize, make_byte: impl FnMut(usize) -> u8, ) -> Result<Self, GuardPageError>

Create a guarded and memory-locked secret buffer by writing generated bytes directly into the locked guarded mapping.

The writable data pages are locked before bytes are generated into them. OS-specific dump or fork-exclusion policies are applied where the backend supports them.

pub fn locked_try_from_fn<E>( len: usize, make_byte: impl FnMut(usize) -> Result<u8, E>, ) -> Result<Self, GuardedSecretVecGenerateError<E>>

Create a guarded and memory-locked secret buffer by fallibly writing generated bytes directly into the locked guarded mapping.

OS-specific dump or fork-exclusion policies are applied where the backend supports them. If generation fails, partial bytes are cleared before the error is returned.

pub const fn len(&self) -> usize

Number of initialized secret bytes.

pub const fn is_empty(&self) -> bool

Returns true when no bytes are held.

pub const fn capacity(&self) -> usize

Writable data capacity between the guard pages.

pub const fn is_memory_locked(&self) -> bool

Returns true when this guarded mapping was locked with mlock.

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

Actual runtime protections established for the current mapping.

pub const fn protection_request(&self) -> ProtectionRequest

Runtime protection policy requested for the current mapping.

pub fn try_with_secret<R>( &self, inspect: impl FnOnce(&[u8]) -> R, ) -> Result<R, CanaryCorruptedError>

Run a closure with read-only access to initialized secret bytes.

pub fn try_with_secret_mut<R>( &mut self, edit: impl FnOnce(&mut [u8]) -> R, ) -> Result<R, CanaryCorruptedError>

Run a closure with mutable access to initialized secret bytes.

pub fn try_extend_from_slice( &mut self, bytes: &[u8], ) -> Result<(), SecretIntegrityError<GuardPageError>>

Append bytes, growing into a new guarded mapping if needed.

pub fn try_replace_from_slice( &mut self, bytes: &[u8], ) -> Result<(), SecretIntegrityError<GuardPageError>>

Replace all initialized secret bytes with a new slice.

If the current guarded mapping is large enough, the old writable region is cleared before the new bytes are copied in. If the new value requires a larger mapping, a replacement mapping is allocated with the same lock state, populated with the new bytes, and then the old mapping is cleared before it is unmapped.

pub fn try_replace_from_fn( &mut self, len: usize, make_byte: impl FnMut(usize) -> u8, ) -> Result<(), SecretIntegrityError<GuardPageError>>

Replace all initialized secret bytes with generated bytes.

A replacement mapping is allocated with the same lock state and populated before the old mapping is cleared and swapped out.

pub fn try_replace_from_fallible_fn<E>( &mut self, len: usize, make_byte: impl FnMut(usize) -> Result<u8, E>, ) -> Result<(), SecretIntegrityError<GuardedSecretVecGenerateError<E>>>

Replace all initialized secret bytes with fallibly generated bytes.

The old guarded value remains unchanged if mapping setup or generation fails. Any partial generated bytes are cleared when the replacement mapping is dropped.

pub fn clear_secret(&mut self)

Clear the full writable data region and reset initialized length.

pub fn into_cleared(self)

Consume this value after first clearing the full writable data region.

Drop still runs after this method returns, so locked mappings are unlocked and the guarded mapping is unmapped normally.

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

Clear the full writable data region with volatile writes, flush the cache lines covering that region, and reset initialized length.

pub fn try_constant_time_eq( &self, other: &[u8], ) -> Result<bool, CanaryCorruptedError>

Compare against a byte slice without early exit for equal-length inputs.

Length mismatch returns immediately because the provided slice length is treated as public metadata.

The portable fallback is intended to avoid data-dependent early exit, but it is not a formal hardware-level constant-time guarantee. On x86_64 or AArch64, enable asm-compare for a stronger compiler boundary.

pub fn verify_integrity(&self) -> Result<(), CanaryCorruptedError>

Verify guarded mapping canaries.

pub fn with_secret_or_panic<R>(&self, inspect: impl FnOnce(&[u8]) -> R) -> R

Run a closure with shared access, panicking on canary corruption.

pub fn with_secret_mut_or_panic<R>( &mut self, edit: impl FnOnce(&mut [u8]) -> R, ) -> R

Run a closure with mutable access, panicking on canary corruption.

pub fn constant_time_eq_or_panic(&self, other: &[u8]) -> bool

Compare, panicking on canary corruption.

Trait Implementations

impl CacheFlushSanitize for GuardedSecretVec

Available on crate feature cache-flush only.

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

Clear this value, then try to flush the cache lines covering its storage.

impl ConstantTimeEq for GuardedSecretVec

fn ct_eq(&self, other: &Self) -> Choice

Compare without secret-dependent early exit.

fn ct_ne(&self, other: &Rhs) -> Choice

Negated ConstantTimeEq::ct_eq.

impl ConstantTimeEq for GuardedSecretVec

Available on crate feature guard-pages and not (miri) only.

fn ct_eq(&self, other: &Self) -> Choice

Determine if two items are equal.

fn ct_ne(&self, other: &Self) -> Choice

Determine if two items are NOT equal.

impl ConstantTimeEq<[u8]> for GuardedSecretVec

fn ct_eq(&self, other: &[u8]) -> Choice

Compare without secret-dependent early exit.

fn ct_ne(&self, other: &Rhs) -> Choice

Negated ConstantTimeEq::ct_eq.

impl Debug for GuardedSecretVec

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

Formats the value using the given formatter.

impl Drop for GuardedSecretVec

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 From<GuardedSecretString> for GuardedSecretVec

Available on crate feature guard-pages and (Android, or DragonFly BSD, or FreeBSD, or iOS, or macOS, or NetBSD, or OpenBSD, or Windows, or Linux and (AArch64 or x86-64)) and not (miri) only.

fn from(secret: GuardedSecretString) -> Self

Converts to this type from the input type.

impl SecureSanitize for GuardedSecretVec

fn secure_sanitize(&mut self)

Clear the sensitive bytes owned by this value.

impl Send for GuardedSecretVec

impl TryFrom<GuardedSecretVec> for GuardedSecretString

Available on crate feature guard-pages and (Android, or DragonFly BSD, or FreeBSD, or iOS, or macOS, or NetBSD, or OpenBSD, or Windows, or Linux and (AArch64 or x86-64)) and not (miri) only.

type Error = SecretTextIntegrityError

The type returned in the event of a conversion error.

fn try_from(secret: GuardedSecretVec) -> Result<Self, Self::Error>

Performs the conversion.

impl Zeroize for GuardedSecretVec

Available on crate feature guard-pages and not (miri) only.

fn zeroize(&mut self)

Zero out this object from memory using Rust intrinsics which ensure the zeroization operation is not “optimized away” by the compiler.

impl ZeroizeOnDrop for GuardedSecretVec

Available on crate feature guard-pages and not (miri) only.