Skip to main content

Secret

Struct Secret 

Source
pub struct Secret<T: Zeroize>(/* private fields */);
Expand description

A value that must never reach a log, a panic message, or a debug dump — only its length may be rendered.

T is almost always a String: a typed password, a Wi-Fi passphrase. Secret::new wraps it, Secret::expose is the one sanctioned way back out, and Debug is implemented once, here, instead of by hand at every call site that holds one.

Implementations§

Source§

impl<T: Zeroize> Secret<T>

Source

pub fn new(value: T) -> Self

Wraps a value so it can only leave through Secret::expose or Secret::into_inner. Always safe: wrapping does not expose anything, which is why Secret<T>: From<T> also exists as a shorthand for this.

Source

pub fn expose(&self) -> &T

The value. Named to be greppable: every caller is a place the secret leaves this type, and there should be exactly one per use site — the place it is actually sent to PAM, greetd, or NetworkManager.

Source

pub fn into_inner(self) -> T
where T: Default,

Unwraps by value, for the rare case a secret needs to move (std::mem::take and hand it to something that owns it next). Still not a way to see the value — the caller has to expose() it separately, same as anyone else. Requires Default because this type erases itself on drop, and Rust will not let a field move out of something with a Drop impl — so the value is swapped for a default one, which is then what gets erased. The caller owns the real value afterwards and owns the job of clearing it, exactly as they would have anyway.

Trait Implementations§

Source§

impl<T: Clone + Zeroize> Clone for Secret<T>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<T: SecretLen + Zeroize> Debug for Secret<T>

Source§

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

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

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

Source§

fn default() -> Self

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

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

Erased when it goes out of scope.

This is the half Debug cannot do. Hiding the value from a log stops it being written down; it does nothing about the copy sitting in the process’s heap until that page is reused, which a core dump or a swapped-out page can still carry.

It matters more here than it looks, because of how the value is accumulated. A typed password is not appended to in place — the host hands the whole string over on every keystroke and the old Secret is dropped — so entering eight characters allocates eight strings, each holding a prefix of the password, and before this each of them was freed with its contents intact. Zeroing on drop clears every one of them at the moment it stops being used.

What it still does not cover, and the README says so: PAM and greetd keep copies of their own once the answer is handed over, and nothing on this side can reach those.

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: Eq + Zeroize> Eq for Secret<T>

Source§

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

Renders <N chars>, never the value — the whole point of the type.

This is the one place that decision is made. Every caller that holds a Secret<T>, including one nested inside a #[derive(Debug)] struct, gets this rendering for free and cannot accidentally derive past it. Wrapping is always safe, so .into() is allowed rather than making every call site spell out Secret::new.

Deliberately one-directional: there is no From<Secret<T>> for T, because taking a value back out is the operation that has to stay greppable, and that is what Secret::expose is for.

Source§

fn from(value: T) -> Self

Converts to this type from the input type.
Source§

impl<T: PartialEq + Zeroize> PartialEq for Secret<T>

Source§

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

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl<T: PartialEq + Zeroize> StructuralPartialEq for Secret<T>

Auto Trait Implementations§

§

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

§

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> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
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> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
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.