Expand description
Secret
wrapper type for more carefully handling secret values
(e.g. passwords, cryptographic keys, access tokens or other credentials)
Goals
- Make secret access explicit and easy-to-audit via the
ExposeSecret
trait. This also makes secret values immutable which helps avoid making accidental copies (e.g. reallocating the backing buffer for aVec
) - Prevent accidental leakage of secrets via channels like debug logging
- Ensure secrets are wiped from memory on drop securely
(using the
zeroize
crate)
Presently this crate favors a simple, no_std
-friendly, safe i.e.
forbid(unsafe_code)
-based implementation and does not provide more advanced
memory protection mechanisms e.g. ones based on mlock(2)
/mprotect(2)
.
We may explore more advanced protection mechanisms in the future.
Box
, String
, and Vec
wrappers
Most users of this crate will simply want Secret
wrappers around Rust’s
core collection types: i.e. Box
, String
, and Vec
.
When the alloc
feature of this crate is enabled (which it is by default),
SecretBox
, SecretString
, and SecretVec
type aliases are
available.
There’s nothing particularly fancy about these: they’re just the simple
composition of Secret<Box<_>>
, Secret<String>
, and Secret<Vec<_>>
!
However, in many cases they’re all you will need.
Advanced usage
If you are hitting limitations on what’s possible with the collection type wrappers, you’ll want to define your own newtype which lets you customize the implementation:
use secrecy::{CloneableSecret, DebugSecret, Secret, Zeroize};
#[derive(Clone)]
pub struct AccountNumber(String);
impl Zeroize for AccountNumber {
fn zeroize(&mut self) {
self.0.zeroize();
}
}
/// Permits cloning
impl CloneableSecret for AccountNumber {}
/// Provides a `Debug` impl (by default `[[REDACTED]]`)
impl DebugSecret for AccountNumber {}
/// Use this alias when storing secret values
pub type SecretAccountNumber = Secret<AccountNumber>;
serde
support
When the serde
feature of this crate is enabled, the Secret
type will
receive a Deserialize
impl for all Secret<T>
types where
T: DeserializeOwned
. This allows loading secret values from data
deserialized from serde
(be careful to clean up any intermediate secrets
when doing this, e.g. the unparsed input!)
To prevent exfiltration of secret values via serde
, by default Secret<T>
does not receive a corresponding Serialize
impl. If you would like
types of Secret<T>
to be serializable with serde
, you will need to impl
the SerializableSecret
marker trait on T
.
Re-exports
pub use zeroize;
Structs
- Wrapper type for values that contains secrets, which attempts to limit accidental exposure and ensure secrets are wiped from memory when dropped. (e.g. passwords, cryptographic keys, access tokens or other credentials)
Traits
- Marker trait for secrets which are allowed to be cloned
- Debugging trait which is specialized for handling secret values
- Expose a reference to an inner secret
- Trait for securely erasing values from memory.
Type Aliases
Box
types containing a secret value- Secret strings
Vec
types containing secret value