secure_gate/traits/
mod.rs

1// # Traits for Polymorphic Secret Handling
2//
3// This module provides the fundamental traits for working with secrets in a polymorphic,
4// zero-cost way. These traits enable generic code that can operate on different secret
5// wrapper types while maintaining strong security guarantees.
6//
7// ## Traits Overview
8//
9// - [`ExposeSecret`] - Read-only secret access with metadata
10// - [`ExposeSecretMut`] - Mutable secret access
11// - [`CloneableType`] - Opt-in safe cloning with zeroization (requires cloneable feature)
12// - [`ConstantTimeEq`] - Constant-time equality to prevent timing attacks (requires ct-eq feature)
13// - [`SecureEncoding`] - Umbrella trait for secure byte encoding to strings (requires encoding features)
14// - [`SecureDecoding`] - Umbrella trait for secure decoding from strings (requires encoding features)
15// - [`SerializableType`] - Marker for types allowing secure serialization (requires serde-serialize feature)
16//
17// ## Security Guarantees
18//
19// - **Read-only enforcement**: Random and encoding wrappers only expose read-only access
20// - **Controlled mutability**: Core wrappers provide full access while others remain read-only
21// - **Zero-cost abstractions**: All traits use `#[inline(always)]` for optimal performance
22// - **Type safety**: Polymorphic operations preserve secret wrapper invariants
23//
24// ## Feature Gates
25//
26// Some traits require optional Cargo features:
27// - rand: Enables random wrapper implementations
28// - cloneable: Enables [`CloneableType`] for safe cloning
29// - ct-eq: Enables [`ConstantTimeEq`] for constant-time comparisons
30// - encoding (or encoding-hex, encoding-base64, encoding-bech32): Enables [`SecureEncoding`] and [`SecureDecoding`] for byte encoding/decoding
31// - serde-serialize: Enables [`SerializableType`] for opt-in serialization
32pub mod expose_secret;
33pub use expose_secret::ExposeSecret;
34
35pub mod expose_secret_mut;
36pub use expose_secret_mut::ExposeSecretMut;
37
38#[cfg(feature = "ct-eq")]
39pub mod constant_time_eq;
40#[cfg(feature = "ct-eq")]
41pub use constant_time_eq::ConstantTimeEq;
42
43#[cfg(feature = "ct-eq-hash")]
44pub mod constant_time_eq_ext;
45#[cfg(feature = "ct-eq-hash")]
46pub use constant_time_eq_ext::ConstantTimeEqExt;
47
48pub mod decoding;
49pub mod encoding;
50
51pub(crate) mod helpers;
52
53#[cfg(feature = "ct-eq-hash")]
54pub(crate) use helpers::ct_eq_hash::ct_eq_hash_bytes;
55
56#[cfg(feature = "encoding-base64")]
57pub use decoding::FromBase64UrlStr;
58#[cfg(feature = "encoding-bech32")]
59pub use decoding::FromBech32Str;
60#[cfg(feature = "encoding-bech32")]
61pub use decoding::FromBech32mStr;
62#[cfg(feature = "encoding-hex")]
63pub use decoding::FromHexStr;
64
65#[cfg(feature = "encoding-base64")]
66pub use encoding::ToBase64Url;
67#[cfg(feature = "encoding-bech32")]
68pub use encoding::ToBech32;
69#[cfg(feature = "encoding-bech32")]
70pub use encoding::ToBech32m;
71#[cfg(feature = "encoding-hex")]
72pub use encoding::ToHex;
73
74/// Marker trait for types that support secure encoding operations.
75///
76/// This trait is automatically implemented for any type that can be viewed as a byte slice
77/// (i.e., implements `AsRef<[u8]>`), such as `&[u8]`, `Vec<u8>`, and byte arrays.
78/// It serves as a bound for blanket implementations of encoding traits like [`ToHex`],
79/// [`ToBase64Url`], and [`ToBech32`], ensuring only appropriate types can perform encoding.
80///
81/// Since this is a marker trait with no methods, it does not add functionality but enables
82/// extension traits to be available where relevant.
83#[cfg(any(
84    feature = "encoding-hex",
85    feature = "encoding-base64",
86    feature = "encoding-bech32"
87))]
88pub trait SecureEncoding {}
89
90#[cfg(any(
91    feature = "encoding-hex",
92    feature = "encoding-base64",
93    feature = "encoding-bech32"
94))]
95impl<T: AsRef<[u8]> + ?Sized> SecureEncoding for T {}
96
97/// Marker trait for types that support secure decoding operations.
98///
99/// This trait is automatically implemented for any type that can be viewed as a string slice
100/// (i.e., implements `AsRef<str>`), such as `&str`, `String`, and string slices.
101/// It serves as a bound for blanket implementations of decoding traits like [`FromHexStr`],
102/// [`FromBase64UrlStr`], and [`FromBech32Str`], ensuring only appropriate types can perform decoding.
103///
104/// Since this is a marker trait with no methods, it does not add functionality but enables
105/// extension traits to be available where relevant.
106#[cfg(any(
107    feature = "encoding-hex",
108    feature = "encoding-base64",
109    feature = "encoding-bech32"
110))]
111pub trait SecureDecoding {}
112
113#[cfg(any(
114    feature = "encoding-hex",
115    feature = "encoding-base64",
116    feature = "encoding-bech32"
117))]
118impl<T: AsRef<str> + ?Sized> SecureDecoding for T {}
119
120#[cfg(feature = "cloneable")]
121pub mod cloneable_type;
122#[cfg(feature = "cloneable")]
123pub use cloneable_type::CloneableType;
124
125#[cfg(feature = "serde-serialize")]
126pub mod serializable_type;
127#[cfg(feature = "serde-serialize")]
128pub use serializable_type::SerializableType;
secure_gate/traits/mod.rs

secure_gate/traits/
mod.rs
