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>
impl<T: Zeroize> Secret<T>
Sourcepub fn new(value: T) -> Self
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.
Sourcepub fn expose(&self) -> &T
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.
Sourcepub fn into_inner(self) -> Twhere
T: Default,
pub fn into_inner(self) -> Twhere
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: Zeroize> Drop for Secret<T>
Erased when it goes out of scope.
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.
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.
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.