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/// ```
21///
22/// Private alias:
23/// ```
24/// use secure_gate::fixed_alias;
25/// fixed_alias!(private_key, 32); // No visibility modifier = private
26/// ```
27///
28/// With custom visibility:
29/// ```
30/// use secure_gate::fixed_alias;
31/// fixed_alias!(pub(crate) InternalKey, 64); // Crate-visible
32/// ```
33///
34/// The generated type is zero-cost and works with all features.
35/// For random initialization, use Type::generate() (requires 'rand' feature).
36#[macro_export]
37macro_rules! fixed_alias {
38    ($vis:vis $name:ident, $size:literal) => {
39        #[doc = concat!("Fixed-size secure secret (", stringify!($size), " bytes)")]
40        const _: () = { let _ = [(); $size][0]; };
41        $vis type $name = $crate::Fixed<[u8; $size]>;
42    };
43    ($name:ident, $size:literal) => {
44        #[doc = concat!("Fixed-size secure secret (", stringify!($size), " bytes)")]
45        const _: () = { let _ = [(); $size][0]; };
46        type $name = $crate::Fixed<[u8; $size]>;
47    };
48}
49
50/// Creates a generic (const-sized) fixed secure buffer type.
51///
52/// This macro generates a type alias to `Fixed<[u8; N]>` with a custom doc string.
53/// Useful for libraries providing generic secret buffers.
54///
55/// # Examples
56///
57/// With custom doc:
58/// ```
59/// use secure_gate::fixed_generic_alias;
60/// fixed_generic_alias!(pub GenericBuffer, "Generic secure byte buffer");
61/// ```
62///
63/// With default doc:
64/// ```
65/// use secure_gate::fixed_generic_alias;
66/// fixed_generic_alias!(pub(crate) Buffer);
67/// ```
68/// For random initialization, use Type::<N>::generate() (requires 'rand' feature).
69#[macro_export]
70macro_rules! fixed_generic_alias {
71    ($vis:vis $name:ident, $doc:literal) => {
72        #[doc = $doc]
73        $vis type $name<const N: usize> = $crate::Fixed<[u8; N]>;
74    };
75    ($vis:vis $name:ident) => {
76        #[doc = "Fixed-size secure byte buffer"]
77        $vis type $name<const N: usize> = $crate::Fixed<[u8; N]>;
78    };
79}
80
81/// Creates a type alias for a random-only fixed-size secret.
82///
83/// This macro generates a type alias to `FixedRng<N>`, which can only be
84/// instantiated via `.generate()` (requires the "rand" feature).
85///
86/// # Examples
87///
88/// Public alias:
89/// ```
90/// #[cfg(feature = "rand")]
91/// {
92/// use secure_gate::fixed_alias_rng;
93/// fixed_alias_rng!(pub MasterKey, 32);
94/// # }
95/// ```
96///
97/// Private alias:
98/// ```
99/// #[cfg(feature = "rand")]
100/// {
101/// use secure_gate::fixed_alias_rng;
102/// fixed_alias_rng!(PrivateKey, 32); // No visibility modifier = private
103/// # }
104/// ```
105/// Instantiate with Type::generate() (requires 'rand' feature).
106#[macro_export]
107macro_rules! fixed_alias_rng {
108    ($vis:vis $name:ident, $size:literal) => {
109        #[doc = concat!("Random-only fixed-size secret (", stringify!($size), " bytes)")]
110        const _: () = { let _ = [(); $size][0]; };
111        $vis type $name = $crate::random::FixedRng<$size>;
112    };
113    ($name:ident, $size:literal) => {
114        #[doc = concat!("Random-only fixed-size secret (", stringify!($size), " bytes)")]
115        const _: () = { let _ = [(); $size][0]; };
116        type $name = $crate::random::FixedRng<$size>;
117    };
118}
119
120/// Creates a type alias for a heap-allocated secure secret.
121///
122/// # Examples
123///
124/// Public alias:
125/// ```
126/// #[cfg(feature = "std")]
127/// {
128/// use secure_gate::dynamic_alias;
129/// dynamic_alias!(pub Password, String);
130/// let pw: Password = "hunter2".into();
131/// assert_eq!(pw.expose_secret(), "hunter2");
132/// # }
133/// ```
134///
135/// Private alias:
136/// ```
137/// #[cfg(feature = "std")]
138/// {
139/// use secure_gate::dynamic_alias;
140/// dynamic_alias!(SecretString, String); // No visibility modifier = private
141/// let secret = SecretString::new("hidden".to_string());
142/// # }
143/// ```
144#[macro_export]
145macro_rules! dynamic_alias {
146    ($vis:vis $name:ident, $inner:ty) => {
147        #[doc = concat!("Secure heap-allocated ", stringify!($inner))]
148        $vis type $name = $crate::Dynamic<$inner>;
149    };
150    ($name:ident, $inner:ty) => {
151        #[doc = concat!("Secure heap-allocated ", stringify!($inner))]
152        type $name = $crate::Dynamic<$inner>;
153    };
154}
155
156/// Creates a generic heap-allocated secure secret type alias.
157///
158/// # Examples
159///
160/// ```
161/// #[cfg(feature = "std")]
162/// {
163/// use secure_gate::dynamic_generic_alias;
164/// dynamic_generic_alias!(pub SecureVec, Vec<u8>, "Secure dynamic byte vector");
165/// let vec = SecureVec::new(vec![1, 2, 3]);
166/// assert_eq!(vec.len(), 3);
167/// # }
168/// ```
169#[macro_export]
170macro_rules! dynamic_generic_alias {
171    ($vis:vis $name:ident, $inner:ty, $doc:literal) => {
172        #[doc = $doc]
173        $vis type $name = $crate::Dynamic<$inner>;
174    };
175    ($vis:vis $name:ident, $inner:ty) => {
176        #[doc = concat!("Secure heap-allocated ", stringify!($inner))]
177        $vis type $name = $crate::Dynamic<$inner>;
178    };
179}
secure_gate/macros.rs

secure_gate/
macros.rs
