secure-gate 0.9.0-rc.5

Secure wrappers for secrets with explicit access and mandatory zeroization — no_std-compatible, zero-overhead library with audit-friendly access patterns.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

//! Owned zeroizing wrapper for encoded secret strings.
//!
//! > **Import path:** `use secure_gate::EncodedSecret;`
//!
//! [`EncodedSecret`] wraps `Zeroizing<String>` with `Debug` → `[REDACTED]`. It is
//! returned by all `*_zeroizing` encoding methods (`to_hex_zeroizing`,
//! `to_base64url_zeroizing`, `try_to_bech32_zeroizing`, etc.).
//!
//! Prefer zeroizing variants when the encoded form is sensitive (private keys, tokens).
//! Use plain `String` variants for public encodings (addresses, transaction IDs).
//!
//! This is **not** a secret wrapper like [`Fixed`](crate::Fixed) / [`Dynamic`](crate::Dynamic)
//! — it is a zeroizing `String` wrapper for encoded output. It implements
//! `Deref<Target = str>` and `Display`.

#[cfg(feature = "alloc")]
/// Owned wrapper for encoded secret strings. Guarantees zeroization on drop
/// while redacting `Debug` output. Use this when the encoded form remains sensitive
/// (e.g. full PEM keys, long-lived Bech32 private keys, tokens).
///
/// See the zeroizing encoding methods on [`Fixed`] and [`Dynamic`] (e.g.
/// [`to_hex_zeroizing`](crate::Fixed::to_hex_zeroizing)).
#[must_use = "dropping EncodedSecret may immediately zeroize encoded output"]
pub struct EncodedSecret(zeroize::Zeroizing<alloc::string::String>);

#[cfg(feature = "alloc")]
impl EncodedSecret {
    #[cfg(any(
        feature = "encoding-hex",
        feature = "encoding-base64",
        feature = "encoding-bech32",
        feature = "encoding-bech32m",
    ))]
    #[inline(always)]
    pub(crate) fn new(s: alloc::string::String) -> Self {
        Self(zeroize::Zeroizing::new(s))
    }

    /// Consumes self and returns the inner `String`.
    ///
    /// This ends zeroization protection for the encoded output.
    #[inline(always)]
    pub fn into_inner(mut self) -> alloc::string::String {
        core::mem::take(&mut self.0)
    }

    /// Consumes self and returns the underlying `Zeroizing<String>`.
    ///
    /// This is an explicit escape hatch consistent with `InnerSecret`.
    #[inline(always)]
    pub fn into_zeroizing(self) -> zeroize::Zeroizing<alloc::string::String> {
        self.0
    }
}

#[cfg(feature = "alloc")]
impl core::ops::Deref for EncodedSecret {
    type Target = str;

    #[inline(always)]
    fn deref(&self) -> &str {
        &self.0
    }
}

#[cfg(feature = "alloc")]
impl core::fmt::Debug for EncodedSecret {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.write_str("[REDACTED]")
    }
}

#[cfg(feature = "alloc")]
impl core::convert::AsRef<str> for EncodedSecret {
    fn as_ref(&self) -> &str {
        &self.0
    }
}

#[cfg(feature = "alloc")]
impl core::convert::AsRef<[u8]> for EncodedSecret {
    fn as_ref(&self) -> &[u8] {
        self.0.as_ref()
    }
}

#[cfg(feature = "alloc")]
impl core::fmt::Display for EncodedSecret {
    /// Outputs the encoded secret content.
    ///
    /// Unlike `Debug` (which prints `[REDACTED]`), `Display` is intentionally transparent
    /// so the value can be written to a sink or used in format strings.
    /// **Do not log with `{}` in production** — prefer `Debug` for diagnostic output
    /// to avoid accidental secret exposure in log files.
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        core::fmt::Display::fmt(&**self, f)
    }
}