Struct LockedSecretString 

pub struct LockedSecretString { /* private fields */ }

UTF-8 text stored in a private platform mapping locked against paging.

This wrapper delegates allocation, locking, dump/fork exclusion, canary handling, growth, clearing, unlocking, and unmapping to LockedSecretVec. It exposes only str/mut str access, so safe Rust cannot invalidate UTF-8.

Implementations

impl LockedSecretString

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

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

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

Allocate locked text with the profile-hardened-native policy.

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

Allocate locked text with the profile-hardened-linux policy.

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

Allocate text storage 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, MemoryLockError>

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

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

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

The original string allocation is volatile-cleared whether mapping setup succeeds or fails. The locked mapping necessarily receives a copy because it does not use the Rust global allocator.

pub fn from_locked_secret_vec( inner: LockedSecretVec, ) -> Result<Self, SecretTextIntegrityError>

Wrap existing locked 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 locked_len(&self) -> usize

Length of the underlying locked mapping.

pub const fn is_memory_locked(&self) -> bool

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

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 locked 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 locked 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<MemoryLockError>>

Append UTF-8 text, preserving locked storage across growth.

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

Replace all text while preserving locked-storage semantics.

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

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

pub fn clear_secret(&mut self)

Clear the full locked mapping and reset the text length.

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

Clear the locked mapping, 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 underlying locked mapping canaries.

pub fn into_locked_secret_vec(self) -> LockedSecretVec

Return the locked byte container without reallocating.

Trait Implementations

impl ConstantTimeEq for LockedSecretString

Available on non-WebAssembly only.

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 LockedSecretString

Available on crate feature memory-lock and non-WebAssembly 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 LockedSecretString

Available on non-WebAssembly only.

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 LockedSecretString

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

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

Formats the value using the given formatter.

impl From<LockedSecretString> for LockedSecretVec

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

fn from(secret: LockedSecretString) -> Self

Converts to this type from the input type.

impl SecureSanitize for LockedSecretString

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

fn secure_sanitize(&mut self)

Clear the sensitive bytes owned by this value.

impl TryFrom<LockedSecretVec> for LockedSecretString

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

type Error = SecretTextIntegrityError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl Zeroize for LockedSecretString

Available on crate feature memory-lock and non-WebAssembly 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 LockedSecretString

Available on crate feature memory-lock and non-WebAssembly only.