Skip to main content

Secret

Struct Secret 

Source
pub struct Secret<T: SecureSanitize> { /* private fields */ }
Expand description

Clear-on-drop wrapper for non-byte secret types.

This is useful for structs that implement SecureSanitize by clearing their sensitive fields. Like SecretBytes, this wrapper intentionally does not implement Clone, Copy, or secret-printing Debug.

§Clearing Strength

When T = [u8; N], this wrapper clears through SecureSanitize for byte arrays, which uses the same volatile byte clearing primitive as the rest of the crate. For fixed-size byte secrets, still prefer SecretBytes<N>, which avoids implementing Clone, Copy, Deref, AsRef<[u8]>, or secret-printing Debug.

Scalar values such as u64, arrays of sanitizable values, Option<T>, and Result<T, E> implement SecureSanitize directly. With alloc, Box<T>, Vec<T>, and String are supported as well. Construction, drop clearing, and Secret::into_cleared remain available for all of them.

For byte vectors, prefer SecretVec over Secret<Vec<u8>>. Vec<T> is supported for generic sanitizable containers and clears the raw allocation capacity after dropping live elements, but generic exposure is intentionally unavailable because Vec<T> does not implement the storage-stability contracts. SecretVec provides reviewed scoped access and rotation that clears old allocations before release.

Implementations§

Source§

impl<T: SecureSanitize> Secret<T>

Source

pub const fn new(inner: T) -> Self

Wrap a sanitizable value.

Source

pub fn into_cleared(self)

Consume the wrapper after first clearing the wrapped value.

Source§

impl<T: StableSharedSecretStorage> Secret<T>

Source

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

Run a closure with shared access to storage certified as shared-stable.

This method is unavailable for types such as Vec<T>, String, and interior-mutable reallocating containers. Use a dedicated secret container or implement StableSharedSecretStorage after reviewing the type’s complete safe shared API.

The returned value cannot borrow the wrapped secret:

ⓘ
use sanitization::Secret;

let secret = Secret::new([1_u8, 2, 3, 4]);
let escaped = secret.with_secret(|bytes| bytes);
let _ = escaped;
Source§

impl<T: StableMutableSecretStorage> Secret<T>

Source

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

Run a closure with mutable access to storage certified as mutable-stable.

This method is unavailable for generic growable or reallocating containers. Prefer SecretVec, SecretString, their bounded variants, or a reviewed fixed-storage type carrying StableMutableSecretStorage.

Trait Implementations§

Source§

impl<T: SecureSanitize> Debug for Secret<T>

Source§

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

Formats the value using the given formatter. Read more
Source§

impl<T: SecureSanitize + Default> Default for Secret<T>

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl<'de, T> Deserialize<'de> for Secret<T>
where T: SecureSanitize + Deserialize<'de>,

Source§

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
Source§

impl<T: SecureSanitize> Drop for Secret<T>

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

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. Read more
Source§

impl<T: SecureSanitize> SecureSanitize for Secret<T>

Source§

fn secure_sanitize(&mut self)

Clear the sensitive bytes owned by this value.
Source§

impl<T> Serialize for Secret<T>
where T: SecureSanitize,

Source§

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

Serialize this value into the given Serde serializer. Read more
Source§

impl<T: StableMutableSecretStorage> StableMutableSecretStorage for Secret<T>

Source§

impl<T: StableSharedSecretStorage> StableSharedSecretStorage for Secret<T>

Source§

impl<T: SecureSanitize> Zeroize for Secret<T>

Source§

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.
Source§

impl<T: SecureSanitize> ZeroizeOnDrop for Secret<T>

Auto Trait Implementations§

§

impl<T> Forget for Secret<T>

§

impl<T> Freeze for Secret<T>
where T: Freeze,

§

impl<T> Move for Secret<T>

§

impl<T> RefUnwindSafe for Secret<T>
where T: RefUnwindSafe,

§

impl<T> Send for Secret<T>
where T: Send,

§

impl<T> Sync for Secret<T>
where T: Sync,

§

impl<T> Unpin for Secret<T>
where T: Unpin,

§

impl<T> UnsafeUnpin for Secret<T>
where T: UnsafeUnpin,

§

impl<T> UnwindSafe for Secret<T>
where T: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.