secure_gate/
macros.rs

1// ==========================================================================
2// src/macros.rs
3// ==========================================================================
4
5/// Creates a type alias for a fixed-size secure secret.
6///
7/// This macro generates a type alias to `Fixed<[u8; N]>` with optional visibility.
8/// The generated type inherits all methods from `Fixed`, including `.expose_secret()`.
9///
10/// # Syntax
11///
12/// - `fixed_alias!(vis Name, size);` — visibility required (e.g., `pub`, `pub(crate)`, or omit for private)
13///
14/// # Examples
15///
16/// Public alias:
17/// ```
18/// use secure_gate::fixed_alias;
19/// fixed_alias!(pub Aes256Key, 32);
20/// let key = Aes256Key::new([0u8; 32]);
21/// assert_eq!(key.len(), 32);
22/// ```
23///
24/// Private alias:
25/// ```
26/// use secure_gate::fixed_alias;
27/// fixed_alias!(private_key, 32); // No visibility modifier = private
28/// ```
29///
30/// With custom visibility:
31/// ```
32/// use secure_gate::fixed_alias;
33/// fixed_alias!(pub(crate) InternalKey, 64); // Crate-visible
34/// ```
35///
36/// The generated type is zero-cost and works with all features.
37#[macro_export]
38macro_rules! fixed_alias {
39    ($vis:vis $name:ident, $size:literal) => {
40        #[doc = concat!("Fixed-size secure secret (", $size, " bytes)")]
41        $vis type $name = $crate::Fixed<[u8; $size]>;
42    };
43}
44
45/// Creates a generic (const-sized) fixed secure buffer type.
46///
47/// This macro generates a type alias to `Fixed<[u8; N]>` with a custom doc string.
48/// Useful for libraries providing generic secret buffers.
49///
50/// # Examples
51///
52/// With custom doc:
53/// ```
54/// use secure_gate::fixed_generic_alias;
55/// fixed_generic_alias!(pub GenericKey, "Generic secure key buffer");
56/// let key: GenericKey<32> = GenericKey::new([0u8; 32]);
57/// ```
58///
59/// With default doc:
60/// ```
61/// use secure_gate::fixed_generic_alias;
62/// fixed_generic_alias!(pub(crate) Buffer);
63/// let buf: Buffer<16> = Buffer::new([0u8; 16]);
64/// ```
65#[macro_export]
66macro_rules! fixed_generic_alias {
67    ($vis:vis $name:ident, $doc:literal) => {
68        #[doc = $doc]
69        $vis type $name<const N: usize> = $crate::Fixed<[u8; N]>;
70    };
71    ($vis:vis $name:ident) => {
72        #[doc = "Fixed-size secure byte buffer"]
73        $vis type $name<const N: usize> = $crate::Fixed<[u8; N]>;
74    };
75}
76
77/// Creates a type alias for a random-only fixed-size secret.
78///
79/// This macro generates a type alias to `FixedRng<N>`, which can only be
80/// instantiated via `.generate()` (requires the "rand" feature).
81///
82/// # Examples
83///
84/// ```
85/// # #[cfg(feature = "rand")]
86/// # {
87/// use secure_gate::fixed_alias_rng;
88/// fixed_alias_rng!(pub MasterKey, 32);
89/// let key = MasterKey::generate();
90/// assert_eq!(key.len(), 32);
91/// # }
92/// ```
93#[macro_export]
94macro_rules! fixed_alias_rng {
95    ($vis:vis $name:ident, $size:literal) => {
96        #[doc = concat!("Random-only fixed-size secret (", $size, " bytes)")]
97        $vis type $name = $crate::rng::FixedRng<$size>;
98    };
99}
100
101/// Creates a type alias for a heap-allocated secure secret.
102///
103/// # Examples
104///
105/// ```
106/// use secure_gate::dynamic_alias;
107/// dynamic_alias!(pub Password, String);
108/// let pw: Password = "hunter2".into();
109/// assert_eq!(pw.expose_secret(), "hunter2");
110/// ```
111#[macro_export]
112macro_rules! dynamic_alias {
113    ($vis:vis $name:ident, $inner:ty) => {
114        #[doc = concat!("Secure heap-allocated ", stringify!($inner))]
115        $vis type $name = $crate::Dynamic<$inner>;
116    };
117}
118
119/// Creates a generic heap-allocated secure secret type alias.
120///
121/// # Examples
122///
123/// ```
124/// use secure_gate::dynamic_generic_alias;
125/// dynamic_generic_alias!(pub SecureVec, Vec<u8>, "Secure dynamic byte vector");
126/// let vec = SecureVec::new(vec![1, 2, 3]);
127/// assert_eq!(vec.len(), 3);
128/// ```
129#[macro_export]
130macro_rules! dynamic_generic_alias {
131    ($vis:vis $name:ident, $inner:ty, $doc:literal) => {
132        #[doc = $doc]
133        $vis type $name = $crate::Dynamic<$inner>;
134    };
135    ($vis:vis $name:ident, $inner:ty) => {
136        #[doc = concat!("Secure heap-allocated ", stringify!($inner))]
137        $vis type $name = $crate::Dynamic<$inner>;
138    };
139}
secure_gate/macros.rs

secure_gate/
macros.rs
