Struct SecretBoxBytes 

pub struct SecretBoxBytes { /* private fields */ }

Fixed-allocation secret bytes with a runtime length.

This type is available with the alloc feature. Unlike SecretVec, its public API cannot grow or shrink the private backing allocation after construction. Mutable exposure receives only &mut [u8], so safe operations cannot reallocate it. The private Vec<u8> representation exists so bounded constructors can use fallible reservation; the safe API never exposes vector growth or ownership extraction.

Replacement requires the same public length. A replacement value is fully constructed in a separate clear-on-drop allocation before the old allocation is cleared and exchanged. Use SecretVec when the secret length must change over time.

Clearing covers the backing allocation’s full capacity, including any allocator-provided spare bytes.

The type deliberately does not implement Clone, Copy, Deref, AsRef<[u8]>, PartialEq, or secret-printing Debug.

Implementations

impl SecretBoxBytes

pub fn zeroed(len: usize) -> Self

Allocate len zeroed secret bytes.

len must already be validated as trusted public metadata. Like ordinary infallible Rust allocation APIs, allocation failure may abort the process. Use SecretBoxBytes::try_zeroed for untrusted lengths or availability-sensitive code.

pub fn try_zeroed( len: usize, maximum: usize, ) -> Result<Self, SecretBoxBytesBuildError>

Allocate a bounded fixed-length secret without aborting on reserve failure.

The public maximum is checked before allocation. After try_reserve_exact succeeds, resizing to len cannot allocate.

pub fn from_boxed_slice(inner: Box<[u8]>) -> Self

Take ownership of an existing boxed byte slice.

The allocation is not copied. Its complete length is volatile-cleared when this value is cleared or dropped.

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

Allocate fixed-length storage and copy bytes into it.

The slice length must already be validated when it comes from untrusted metadata. Use SecretBoxBytes::try_from_slice to apply a public bound and return allocation failure.

pub fn try_from_slice( bytes: &[u8], maximum: usize, ) -> Result<Self, SecretBoxBytesBuildError>

Copy a bounded slice into fallibly allocated fixed-length storage.

pub fn from_fn(len: usize, make_byte: impl FnMut(usize) -> u8) -> Self

Generate each byte directly into fixed-length clear-on-drop storage.

If the generator panics, the partially initialized value is cleared during unwinding. len must already be trusted and bounded; allocation failure may abort. Use SecretBoxBytes::try_from_fn_bounded for untrusted lengths.

pub fn try_from_fn<E>( len: usize, make_byte: impl FnMut(usize) -> Result<u8, E>, ) -> Result<Self, E>

Generate each byte with a fallible generator.

If generation fails, the partially initialized allocation is cleared before the error is returned. This method only reports generator errors; len must already be trusted and bounded, and allocation failure may abort. Use SecretBoxBytes::try_from_fn_bounded when allocation must also be fallible.

pub fn try_from_fn_bounded<E>( len: usize, maximum: usize, make_byte: impl FnMut(usize) -> Result<u8, E>, ) -> Result<Self, SecretBoxBytesGenerateError<E>>

Generate a bounded fixed-length secret with fallible allocation and fallible byte generation.

pub const fn len(&self) -> usize

Number of initialized bytes in the fixed allocation.

pub const fn is_empty(&self) -> bool

Returns true when the fixed allocation has length zero.

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

Run a closure with direct shared access to the fixed allocation.

The returned value cannot borrow the secret:

use sanitization::SecretBoxBytes;

let secret = SecretBoxBytes::from_slice(b"token");
let escaped = secret.with_secret(|bytes| bytes);
let _ = escaped;

pub fn with_secret_mut<R>(&mut self, edit: impl FnOnce(&mut [u8]) -> R) -> R

Run a closure with direct mutable access to the fixed allocation.

A mutable slice cannot resize or replace the backing allocation.

pub fn copy_to_slice(&self, destination: &mut [u8]) -> Result<(), LengthError>

Copy the secret into a caller-provided slice of the same public length.

pub fn replace_from_slice(&mut self, bytes: &[u8]) -> Result<(), LengthError>

Replace the secret from a same-length slice.

The replacement allocation is constructed before the old allocation is cleared. A length mismatch leaves the existing secret unchanged.

pub fn replace_from_boxed_slice( &mut self, bytes: Box<[u8]>, ) -> Result<(), LengthError>

Replace the secret by taking ownership of a same-length boxed slice.

On length mismatch, the rejected boxed bytes are cleared before this method returns the error.

pub fn replace_from_fn(&mut self, make_byte: impl FnMut(usize) -> u8)

Replace the secret with same-length generated bytes.

The replacement is generated in a fresh clear-on-drop allocation. If generation panics, the old value remains unchanged.

pub fn try_replace_from_fn<E>( &mut self, make_byte: impl FnMut(usize) -> Result<u8, E>, ) -> Result<(), E>

Replace the secret with same-length fallibly generated bytes.

If generation fails, the old value remains unchanged and the partial replacement is cleared before the error is returned.

pub fn clear_secret(&mut self)

Clear every byte while retaining the fixed allocation and length.

pub fn into_cleared(self)

Consume this value after clearing its complete allocation.

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

Compare against a slice without early exit for equal-length inputs.

Length is treated as public metadata.

Trait Implementations

impl ConstantTimeEq for SecretBoxBytes

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

Available on crate feature alloc 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<[u8]> for SecretBoxBytes

Available on crate feature alloc only.

fn ct_eq(&self, other: &[u8]) -> Choice

Compare without secret-dependent early exit.

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

Negated ConstantTimeEq::ct_eq.

impl Debug for SecretBoxBytes

Available on crate feature alloc only.

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

Formats the value using the given formatter.

impl Default for SecretBoxBytes

Available on crate feature alloc only.

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for SecretBoxBytes

Available on crate feature alloc only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Drop for SecretBoxBytes

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 SecretBoxBytes

Available on crate feature alloc only.

fn secure_sanitize(&mut self)

Clear the sensitive bytes owned by this value.

impl Serialize for SecretBoxBytes

Available on crate feature alloc only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StableMutableSecretStorage for SecretBoxBytes

Available on crate feature alloc only.

impl StableSharedSecretStorage for SecretBoxBytes

Available on crate feature alloc only.

impl Zeroize for SecretBoxBytes

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

Available on crate feature alloc only.