Struct GuardedSecretString 

pub struct GuardedSecretString { /* private fields */ }

UTF-8 text stored between inaccessible platform guard pages.

This wrapper delegates guarded mapping ownership, optional memory locking, canary handling, growth, clearing, and unmapping to GuardedSecretVec. It exposes only str/mut str access.

Implementations

impl GuardedSecretString

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

Allocate empty guarded text storage with at least capacity UTF-8 bytes.

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

Allocate guarded text with the profile-guarded-native policy.

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

Allocate guarded text under an explicit runtime protection policy.

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

Fill a runtime-length UTF-8 payload only after all required controls have been established.

The closure receives exactly capacity bytes and returns the number initialized. Invalid UTF-8, partial fill failures, excessive lengths, and canary corruption clear the mapping before returning an error.

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, ProtectedSecretTextFillError<E>>

Bounded policy-aware UTF-8 fill for untrusted capacities.

A capacity above maximum is rejected before mapping or invoking fill.

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

Fill an exact-length UTF-8 payload after required controls succeed.

pub fn from_secret_str(text: &str) -> Result<Self, GuardPageError>

Copy UTF-8 text directly into a guarded platform mapping.

pub fn from_string(text: String) -> Result<Self, GuardPageError>

Move an owned string through clear-on-drop staging into guarded storage.

pub fn locked_from_secret_str(text: &str) -> Result<Self, GuardPageError>

Copy UTF-8 text into a guarded and memory-locked mapping.

pub fn locked_from_string(text: String) -> Result<Self, GuardPageError>

Move an owned string through clear-on-drop staging into a guarded and memory-locked mapping.

pub fn from_guarded_secret_vec( inner: GuardedSecretVec, ) -> Result<Self, SecretTextIntegrityError>

Wrap existing guarded bytes without reallocating after UTF-8 validation.

Invalid input is cleared before core::str::Utf8Error is returned.

pub const fn len(&self) -> usize

Number of initialized UTF-8 bytes.

pub const fn is_empty(&self) -> bool

Returns true when no text is held.

pub const fn capacity(&self) -> usize

Payload capacity in UTF-8 bytes.

pub const fn is_memory_locked(&self) -> bool

Returns true when the writable guarded pages are memory locked.

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

Actual runtime protections established for the underlying mapping.

pub const fn protection_request(&self) -> ProtectionRequest

Runtime protection policy requested for the underlying mapping.

pub fn try_with_secret<R>( &self, inspect: impl FnOnce(&str) -> R, ) -> Result<R, SecretTextIntegrityError>

Run a closure with read-only access to the guarded secret text.

pub fn try_with_secret_mut<R>( &mut self, edit: impl FnOnce(&mut str) -> R, ) -> Result<R, SecretTextIntegrityError>

Run a closure with mutable access to the guarded secret text.

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

Run a closure with shared access, panicking on integrity or UTF-8 failure.

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

Run a closure with mutable access, panicking on integrity or UTF-8 failure.

pub fn try_push_str( &mut self, text: &str, ) -> Result<(), SecretIntegrityError<GuardPageError>>

Append UTF-8 text, preserving guarded and lock-state semantics.

pub fn try_replace_from_secret_str( &mut self, text: &str, ) -> Result<(), SecretIntegrityError<GuardPageError>>

Replace all text while preserving guarded and lock-state semantics.

pub fn try_replace_from_string( &mut self, text: String, ) -> Result<(), SecretIntegrityError<GuardPageError>>

Replace all text from an owned string and clear the source allocation.

pub fn clear_secret(&mut self)

Clear the full writable guarded region and reset the text length.

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

Clear the writable guarded region, then flush its cache lines.

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

Compare against UTF-8 text without early exit for equal-length inputs.

pub fn constant_time_eq_or_panic(&self, other: &str) -> bool

Compare after integrity verification, panicking on canary corruption.

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

Verify the guarded mapping canaries.

pub fn into_guarded_secret_vec(self) -> GuardedSecretVec

Return the guarded byte container without reallocating.

Trait Implementations

impl ConstantTimeEq for GuardedSecretString

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 GuardedSecretString

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<str> for GuardedSecretString

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

Compare without secret-dependent early exit.

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

Negated ConstantTimeEq::ct_eq.

impl Debug 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.

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

Formats the value using the given formatter.

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 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.

fn secure_sanitize(&mut self)

Clear the sensitive bytes owned by this value.

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 GuardedSecretString

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 GuardedSecretString

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