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 new_volatile(inner: String) -> SecretString

Compatibility alias for SecretString::new.

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.

pub fn with_capacity_volatile(capacity: usize) -> SecretString

Compatibility alias for SecretString::with_capacity.

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

Create a secret string by copying from a string slice.

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.

pub fn try_from_chars<E>( char_count: usize, make_char: impl FnMut(usize) -> Result<char, E>, ) -> Result<SecretString, 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.

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

Compatibility alias for SecretString::from_secret_str.

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<(), 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.

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 SecureSanitize for SecretString

Available on crate feature alloc only.

fn secure_sanitize(&mut self)

Clear the sensitive bytes owned by this value.