Struct SecretBytes 

pub struct SecretBytes<const N: usize> { /* private fields */ }

Fixed-size secret byte storage with automatic sanitization on drop.

On targets with 8-bit atomics, each byte is stored as an AtomicU8. Atomic stores are observable side effects, giving a safe, dependency-free clear path without raw pointers or volatile writes. On targets without 8-bit atomics the type remains available through safe core::cell::Cell storage, but clearing cannot claim the same optimizer resistance as the atomic path.

Platform Notes

On targets with 8-bit atomics (target_has_atomic = "8"), this type is Sync and can be shared across threads for read-only access. Mutating and clearing operations require &mut self to prevent partially-cleared multi-byte observations through shared references. On targets without 8-bit atomics, this type uses core::cell::Cell and is !Sync, so static or cross-thread sharing patterns that compile on server targets may not compile on no-atomic embedded targets.

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

Implementations

impl<const N: usize> SecretBytes<N>

pub const fn zeroed() -> Self

Create an all-zero secret buffer.

pub fn from_array(bytes: [u8; N]) -> Self

Create a secret from an array, then best-effort clear the input array.

For the strongest move hygiene, prefer SecretBytes::from_fn or SecretBytes::copy_from_slice so callers can avoid building a normal byte array first.

Examples found in repository

examples/macros.rs (line 12)

fn main() {
    let credentials = SessionCredentials {
        private_key: SecretBytes::from_array([1; 32]),
        nonce: SecretBytes::from_array([2; 12]),
    };

    assert!(credentials.private_key.constant_time_eq(&[1; 32]));
    assert!(credentials.nonce.constant_time_eq(&[2; 12]));
}

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

Create a secret by producing each byte directly.

This avoids requiring a full temporary [u8; N] at the call boundary.

Examples found in repository

examples/basic.rs (line 4)

fn main() {
    let key = SecretBytes::<32>::from_fn(|index| index as u8);

    let key_len = key.expose_secret(|bytes| bytes.len());
    assert_eq!(key_len, 32);
}

pub const fn len(&self) -> usize

Number of bytes stored in this secret.

pub const fn is_empty(&self) -> bool

Returns true when the secret has zero length.

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

Replace all bytes from a same-length slice.

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

Fill a caller-provided destination with a temporary copy of the secret.

pub fn read_byte(&self, index: usize) -> Option<u8>

Read one byte without exposing the whole secret.

pub fn write_byte(&mut self, index: usize, value: u8) -> Result<(), LengthError>

Replace one byte.

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

Call a closure with a temporary array copy, then clear that copy.

This is the narrowest safe way to interoperate with APIs requiring &[u8]. The closure must not retain or return references to the temporary array; Rust’s borrow checker enforces that part. The closure can still intentionally copy bytes elsewhere, so use it only at true cryptographic or protocol boundaries.

If the closure aborts the process, for example under panic = "abort", Rust destructors do not run and the temporary stack copy cannot be cleared. On the normal return path the temporary is cleared eagerly before this method returns; on unwinding panic paths the RAII guard clears it during unwinding.

Examples found in repository

examples/basic.rs (line 6)

fn main() {
    let key = SecretBytes::<32>::from_fn(|index| index as u8);

    let key_len = key.expose_secret(|bytes| bytes.len());
    assert_eq!(key_len, 32);
}

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

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

Length mismatch returns immediately because the provided slice length is treated as public metadata. Prefer fixed-size inputs where possible.

Examples found in repository

examples/macros.rs (line 16)

fn main() {
    let credentials = SessionCredentials {
        private_key: SecretBytes::from_array([1; 32]),
        nonce: SecretBytes::from_array([2; 12]),
    };

    assert!(credentials.private_key.constant_time_eq(&[1; 32]));
    assert!(credentials.nonce.constant_time_eq(&[2; 12]));
}

pub fn constant_time_eq_secret(&self, other: &Self) -> bool

Compare against another secret without early exit.

pub fn secure_clear(&mut self)

Clear all bytes now. This is also called from Drop.

Trait Implementations

impl<const N: usize> Debug for SecretBytes<N>

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

Formats the value using the given formatter.

impl<const N: usize> Default for SecretBytes<N>

fn default() -> Self

Returns the “default value” for a type.

impl<const N: usize> Drop for SecretBytes<N>

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 N: usize> SecureSanitize for SecretBytes<N>

fn secure_sanitize(&mut self)

Clear the sensitive bytes owned by this value.