Struct SecretBuffer 

pub struct SecretBuffer { /* private fields */ }

Owned sensitive bytes with redacted formatting and drop-time cleanup.

SecretBuffer is available with the alloc feature. It is intended for decoded keys, tokens, and other values that should not be accidentally logged. The buffer exposes contents only through explicit reveal methods.

Spare vector capacity is cleared when wrapping owned bytes. On drop, initialized bytes and vector spare capacity are cleared with the crate’s internal best-effort wipe helpers. This is data-retention reduction, not a formal zeroization guarantee, and it cannot make claims about allocator behavior or historical copies outside the wrapper.

Platform Memory Controls

SecretBuffer does not lock its allocation into physical memory. The OS may page its contents to disk, include them in hibernation images, or expose them through crash dumps. High-assurance deployments must combine SecretBuffer with platform memory-locking where available, encrypted or disabled swap, crash-dump suppression, and allocator isolation appropriate for their environment.

On wasm32 targets, the wipe barrier uses only a compiler fence. The wasm runtime JIT may still optimize or retain cleared bytes in ways this crate cannot control. wasm32 builds fail closed by default; enable allow-wasm32-best-effort-wipe only when the deployment explicitly accepts this limitation and applies its own memory strategy around owned secret buffers.

Implementations

impl SecretBuffer

pub fn from_vec(bytes: Vec<u8>) -> Self

Wraps an existing vector as sensitive material.

pub fn from_slice(bytes: &[u8]) -> Self

Copies a slice into an owned sensitive buffer.

pub fn len(&self) -> usize

Returns the number of initialized secret bytes.

pub fn is_empty(&self) -> bool

Returns whether the buffer contains no initialized secret bytes.

pub fn expose_secret(&self) -> &[u8]

Reveals the secret bytes.

This method is intentionally named to make secret access explicit at the call site.

pub fn expose_secret_utf8(&self) -> Result<&str, Utf8Error>

Reveals the secret bytes as UTF-8 text.

This method is intentionally named to make secret access explicit at the call site. Secret material may be arbitrary binary data, so this method is fallible.

pub fn expose_secret_mut(&mut self) -> &mut [u8]

Reveals the secret bytes mutably.

This method is intentionally named to make secret access explicit at the call site.

pub fn into_exposed_vec(self) -> ExposedSecretVec

Consumes the wrapper and returns owned secret bytes.

This is an explicit escape hatch for interop with APIs that require an owned vector-like value. The returned ExposedSecretVec remains redacted by formatting and clears its vector on drop.

pub fn try_into_exposed_string(self) -> Result<ExposedSecretString, Self>

Consumes the wrapper and returns the owned secret bytes as UTF-8 text.

This is an explicit escape hatch for interop with APIs that require an owned string-like value. The returned ExposedSecretString remains redacted by formatting and clears its heap allocation on drop.

If the secret bytes are not valid UTF-8, the original redacted wrapper is returned unchanged.

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

Compares this secret to other without short-circuiting on the first differing byte.

Length and the final equality result remain public. Different lengths return false immediately; use this helper only when the compared lengths are public protocol facts or have been normalized by the caller. For equal-length inputs, this helper scans every byte before returning. It is constant-time-oriented best effort, not a formal cryptographic constant-time guarantee. This comparison is deliberately explicit: redacted buffer types do not implement PartialEq because == would make a best-effort helper look like a formal token/MAC comparison primitive.

Do not use this helper as the sole MAC, bearer-token, password-hash, or authentication-secret comparison primitive in high-assurance systems. Applications that can admit dependencies should use a reviewed constant-time comparison primitive, such as subtle, at the protocol boundary.

pub fn clear(&mut self)

Clears the initialized bytes and makes the buffer empty.

Trait Implementations

impl Debug for SecretBuffer

Available on crate feature alloc only.

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

Formats the value using the given formatter.

impl Display for SecretBuffer

Available on crate feature alloc only.

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

Formats the value using the given formatter.

impl Drop for SecretBuffer

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 CAP: usize> From<DecodedBuffer<CAP>> for SecretBuffer

Available on crate feature alloc only.

fn from(buffer: DecodedBuffer<CAP>) -> Self

Copies visible decoded bytes from a stack-backed buffer into an owned redacted buffer.

The consumed stack-backed buffer clears its backing array when it is dropped at the end of the conversion.

impl<const CAP: usize> From<EncodedBuffer<CAP>> for SecretBuffer

Available on crate feature alloc only.

fn from(buffer: EncodedBuffer<CAP>) -> Self

Copies visible encoded bytes from a stack-backed buffer into an owned redacted buffer.

The consumed stack-backed buffer clears its backing array when it is dropped at the end of the conversion.

impl From<String> for SecretBuffer

Available on crate feature alloc only.

fn from(text: String) -> Self

Wraps an owned UTF-8 string as sensitive material.

The string is consumed without copying its initialized bytes. Spare vector capacity is cleared immediately before the bytes are stored.

impl From<Vec<u8>> for SecretBuffer

Available on crate feature alloc only.

fn from(bytes: Vec<u8>) -> Self

Wraps an owned vector as sensitive material.

Spare capacity is cleared immediately before the vector is stored. Use SecretBuffer::from_slice when the source data is borrowed.

impl FromStr for SecretBuffer

Available on crate feature alloc only.

fn from_str(input: &str) -> Result<Self, Self::Err>

Decodes strict standard padded Base64 text into a redacted owned buffer.

Use crate::Engine::decode_secret or crate::Profile::decode_secret when a different alphabet, padding mode, or line-wrapping profile is required. These conversions always use crate::STANDARD; URL-safe, bcrypt, crypt, MIME, PEM, and custom alphabets must use an explicit engine or profile.

Security

This idiomatic conversion uses the strict standard decoder, not the constant-time-oriented decoder. It may branch or return early on malformed input and reports exact DecodeError positions. For secret-bearing tokens or key material where malformed-input timing matters, use crate::ct::CtEngine::decode_secret through crate::ct::STANDARD, or use staged decode and then wrap the successful output in SecretBuffer.

type Err = DecodeError

The associated error which can be returned from parsing.

impl<const N: usize> TryFrom<&[u8; N]> for SecretBuffer

Available on crate feature alloc only.

fn try_from(input: &[u8; N]) -> Result<Self, Self::Error>

Decodes a strict standard padded Base64 byte array into a redacted owned buffer.

Use crate::Engine::decode_secret or crate::Profile::decode_secret when a different alphabet, padding mode, or line-wrapping profile is required. These conversions always use crate::STANDARD; URL-safe, bcrypt, crypt, MIME, PEM, and custom alphabets must use an explicit engine or profile.

Security

This idiomatic conversion uses the strict standard decoder, not the constant-time-oriented decoder. It may branch or return early on malformed input and reports exact DecodeError positions. For secret-bearing tokens or key material where malformed-input timing matters, use crate::ct::CtEngine::decode_secret through crate::ct::STANDARD, or use staged decode and then wrap the successful output in SecretBuffer.

type Error = DecodeError

The type returned in the event of a conversion error.

impl TryFrom<&[u8]> for SecretBuffer

Available on crate feature alloc only.

fn try_from(input: &[u8]) -> Result<Self, Self::Error>

Decodes strict standard padded Base64 into a redacted owned buffer.

Use crate::Engine::decode_secret or crate::Profile::decode_secret when a different alphabet, padding mode, or line-wrapping profile is required. These conversions always use crate::STANDARD; URL-safe, bcrypt, crypt, MIME, PEM, and custom alphabets must use an explicit engine or profile.

Security

This idiomatic conversion uses the strict standard decoder, not the constant-time-oriented decoder. It may branch or return early on malformed input and reports exact DecodeError positions. For secret-bearing tokens or key material where malformed-input timing matters, use crate::ct::CtEngine::decode_secret through crate::ct::STANDARD, or use staged decode and then wrap the successful output in SecretBuffer.

type Error = DecodeError

The type returned in the event of a conversion error.

impl TryFrom<&str> for SecretBuffer

Available on crate feature alloc only.

fn try_from(input: &str) -> Result<Self, Self::Error>

Decodes strict standard padded Base64 text into a redacted owned buffer.

Use crate::Engine::decode_secret or crate::Profile::decode_secret when a different alphabet, padding mode, or line-wrapping profile is required. These conversions always use crate::STANDARD; URL-safe, bcrypt, crypt, MIME, PEM, and custom alphabets must use an explicit engine or profile.

Security

This idiomatic conversion uses the strict standard decoder, not the constant-time-oriented decoder. It may branch or return early on malformed input and reports exact DecodeError positions. For secret-bearing tokens or key material where malformed-input timing matters, use crate::ct::CtEngine::decode_secret through crate::ct::STANDARD, or use staged decode and then wrap the successful output in SecretBuffer.

type Error = DecodeError

The type returned in the event of a conversion error.