Struct SecretString 

pub struct SecretString { /* private fields */ }

Heap-allocated secret UTF-8 text with clear-on-drop behavior.

This type is available with the alloc feature. Use it for bearer tokens, passphrases, and textual secrets that must cross APIs as UTF-8. Clearing uses volatile writes over the full allocation capacity before the internal byte vector length is set to zero.

Implementations

impl SecretString

pub fn new(inner: String) -> SecretString

Wrap a string using volatile clearing on drop.

pub fn from_string(text: String) -> SecretString

Wrap an existing string using volatile clearing on drop.

This is an explicit ownership-taking alias for SecretString::new. The string allocation is not copied; its full capacity will be volatile-cleared when this SecretString is cleared or dropped.

pub fn from_secret_vec(secret: SecretVec) -> Result<SecretString, Utf8Error>

Convert secret bytes into UTF-8 text without reallocating.

UTF-8 is validated before the byte allocation is transferred. Invalid input is volatile-cleared before core::str::Utf8Error is returned; the rejected secret bytes are not returned to the caller.

pub const fn empty() -> SecretString

Create an empty secret string.

pub fn with_capacity(capacity: usize) -> SecretString

Create an empty secret string with at least the requested byte capacity.

capacity must be trusted and bounded. Allocation failure may abort; use SecretString::try_with_capacity when it must be reported.

pub fn try_with_capacity( capacity: usize, ) -> Result<SecretString, SecretAllocationError>

Create an empty secret string using fallible byte allocation.

Unlike SecretString::with_capacity, this reports capacity overflow or allocation failure instead of panicking or invoking the allocation error handler.

pub fn from_secret_str(text: &str) -> SecretString

Create a secret string by copying from a string slice.

The public byte length must be trusted and bounded. Use SecretString::try_from_secret_str_bounded at untrusted boundaries.

pub fn try_from_secret_str_bounded( text: &str, maximum_bytes: usize, ) -> Result<SecretString, SecretAllocationError>

Copy UTF-8 text after enforcing a public byte-length ceiling and using fallible allocation.

Length validation happens before allocation. The borrowed source is not cleared by this method.

pub fn from_chars( char_count: usize, make_char: impl FnMut(usize) -> char, ) -> SecretString

Create a secret string by generating UTF-8 scalar values directly.

char_count is the number of generated char values, not the final byte length. Each generated character is encoded into the secret heap allocation and the small stack encoding buffer is immediately cleared. char_count must be trusted and bounded; capacity overflow panics and allocation failure may abort.

pub fn try_from_chars<E>( char_count: usize, make_char: impl FnMut(usize) -> Result<char, E>, ) -> Result<SecretString, SecretGenerateError<E>>

Create a secret string by fallibly generating UTF-8 scalar values directly.

If make_char returns an error, any text generated before the error is cleared before the error is returned. This method reports both build failure through SecretGenerateError::Build and generator failure through SecretGenerateError::Generate. It does not enforce an application maximum; use SecretString::try_from_chars_bounded when needed.

pub fn try_from_chars_bounded<E>( char_count: usize, maximum_bytes: usize, make_char: impl FnMut(usize) -> Result<char, E>, ) -> Result<SecretString, SecretGenerateError<E>>

Create secret UTF-8 text with a caller-enforced byte-capacity ceiling.

The worst-case UTF-8 byte capacity is calculated with checked arithmetic and compared with maximum_bytes before allocation or generator execution.

pub fn len(&self) -> usize

Number of bytes currently held.

pub fn is_empty(&self) -> bool

Returns true when no text is held.

pub fn capacity(&self) -> usize

Current allocation capacity in bytes.

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

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

The result is fallible because the text is stored internally as bytes to keep clearing safe without String::as_mut_vec.

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

Run a closure with mutable access to the secret text.

The result is fallible because the text is stored internally as bytes to keep clearing safe without String::as_mut_vec. The closure receives &mut str, so safe Rust cannot invalidate UTF-8.

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

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

pub fn push_str(&mut self, text: &str)

Append text to the secret string.

If capacity must grow, the previous allocation is wiped before it is dropped. Prefer constructing with enough capacity in callers that append repeatedly.

pub fn replace_from_secret_str(&mut self, text: &str)

Replace all text with a new string slice.

If capacity must grow, the old allocation is wiped before it is dropped and the old secret bytes are not copied into the replacement allocation.

pub fn replace_from_string(&mut self, text: String)

Replace all text by taking ownership of an existing string.

The old allocation is cleared before the provided string allocation becomes the secret storage. The provided string is not copied; its full capacity will be volatile-cleared when this SecretString is later cleared or dropped.

pub fn replace_from_chars( &mut self, char_count: usize, make_char: impl FnMut(usize) -> char, )

Replace all text with generated UTF-8 scalar values.

The replacement text is generated into a fresh clear-on-drop allocation before the old value is cleared and replaced. If make_char panics, the old value remains unchanged and partial generated text is cleared during unwinding.

pub fn try_replace_from_chars<E>( &mut self, char_count: usize, make_char: impl FnMut(usize) -> Result<char, E>, ) -> Result<(), SecretGenerateError<E>>

Replace all text with fallibly generated UTF-8 scalar values.

The replacement text is generated into a fresh clear-on-drop allocation before the old value is cleared and replaced. If make_char returns an error, the old value remains unchanged and partial generated text is cleared before the error is returned.

pub fn clear_secret(&mut self)

Clear this value immediately with volatile writes.

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

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

Length mismatch returns immediately because the provided string 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, enable asm-compare for a stronger compiler boundary. Use a dedicated constant-time comparison crate if your protocol requires externally audited timing guarantees.

pub fn into_cleared(self)

Consume the wrapper after first clearing the wrapped string.

pub fn into_secret_vec(self) -> SecretVec

Convert this UTF-8 text into secret bytes without reallocating.

Trait Implementations

impl ConstantTimeEq for SecretString

Available on crate feature alloc only.

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

Compare without secret-dependent early exit.

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

Negated ConstantTimeEq::ct_eq.

impl ConstantTimeEq<str> for SecretString

Available on crate feature alloc 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 SecretString

Available on crate feature alloc only.

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

Formats the value using the given formatter.

impl Default for SecretString

Available on crate feature alloc only.

fn default() -> SecretString

Returns the “default value” for a type.

impl Drop for SecretString

Available on crate feature alloc only.

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 MAX: usize> From<BoundedSecretString<MAX>> for SecretString

Available on crate feature alloc only.

fn from(secret: BoundedSecretString<MAX>) -> SecretString

Converts to this type from the input type.

impl SecureSanitize for SecretString

Available on crate feature alloc only.

fn secure_sanitize(&mut self)

Clear the sensitive bytes owned by this value.

impl TryFrom<SecretVec> for SecretString

Available on crate feature alloc only.

type Error = Utf8Error

The type returned in the event of a conversion error.

fn try_from( secret: SecretVec, ) -> Result<SecretString, <SecretString as TryFrom<SecretVec>>::Error>

Performs the conversion.