lib_q_aead/
lib.rs

1//! lib-Q AEAD - Post-quantum Authenticated Encryption
2//!
3//! This crate provides a flexible, algorithm-agnostic implementation of post-quantum
4//! authenticated encryption with associated data (AEAD). It supports dynamic algorithm
5//! registration and follows libQ's architectural principles.
6
7#![cfg_attr(not(feature = "std"), no_std)]
8// Note: We need unsafe code for global registry initialization
9#![deny(unused_qualifications)]
10
11#[cfg(feature = "alloc")]
12extern crate alloc;
13
14#[cfg(feature = "alloc")]
15use alloc::{
16    boxed::Box,
17    vec::Vec,
18};
19
20// Re-export types: algorithm IDs from `lib-q-types`; crypto API from `lib-q-core`
21pub use lib_q_core::{
22    Aead,
23    AeadKey,
24    Nonce,
25    Result,
26};
27pub use lib_q_types::{
28    Algorithm,
29    AlgorithmCategory,
30};
31
32// Internal modules
33mod metadata;
34mod plugin;
35mod registry;
36pub mod security;
37
38// Re-export public API
39pub use metadata::{
40    AeadMetadata,
41    AeadWithMetadata,
42    PerformanceTier,
43};
44pub use plugin::{
45    AeadPlugin,
46    PluginRegistry,
47};
48pub use registry::AeadRegistry;
49// Re-export security sub-modules for testing
50pub use security::constant_time;
51// Re-export security API
52pub use security::{
53    SecurityConfig,
54    SecurityContext,
55    get_security_config,
56    set_security_config,
57};
58pub use security::{
59    memory,
60    nonce,
61    side_channel,
62    stack_buffer,
63    timing,
64    validation,
65};
66
67#[cfg(feature = "alloc")]
68mod provider;
69#[cfg(feature = "alloc")]
70pub use provider::LibQAeadProvider;
71
72#[cfg(feature = "wasm")]
73mod wasm;
74
75// Macro is exported at crate root via #[macro_export] in plugin.rs
76
77// Algorithm implementations
78#[cfg(feature = "duplex-sponge-aead")]
79mod duplex_aead;
80#[cfg(feature = "rocca-s")]
81mod rocca_s;
82#[cfg(feature = "romulus-m")]
83mod romulus_m;
84#[cfg(feature = "romulus-n")]
85mod romulus_n;
86#[cfg(feature = "saturnin")]
87mod saturnin;
88#[cfg(feature = "shake256")]
89mod shake256;
90#[cfg(feature = "tweak-aead")]
91mod tweak_aead;
92
93// Re-export implementations
94#[cfg(feature = "duplex-sponge-aead")]
95pub use duplex_aead::DuplexSpongeAead;
96#[cfg(feature = "rocca-s")]
97pub use rocca_s::RoccaSAead;
98#[cfg(feature = "romulus-m")]
99pub use romulus_m::RomulusMAead;
100#[cfg(feature = "romulus-n")]
101pub use romulus_n::RomulusNAead;
102#[cfg(feature = "saturnin")]
103pub use saturnin::SaturninAead;
104#[cfg(feature = "shake256")]
105pub use shake256::Shake256Aead;
106#[cfg(feature = "tweak-aead")]
107pub use tweak_aead::TweakAead;
108
109/// Global AEAD registry instance
110///
111/// This uses thread-safe initialization when compiled with std features,
112/// and single-threaded initialization for no_std environments.
113/// The key insight is that when the HPKE crate is compiled with std features,
114/// it expects thread-safe statics, so we need to provide them.
115#[cfg(feature = "std")]
116static REGISTRY: once_cell::sync::Lazy<AeadRegistry> = once_cell::sync::Lazy::new(|| {
117    let registry = AeadRegistry::new();
118
119    // Register built-in algorithms
120    #[cfg(feature = "saturnin")]
121    let _ = registry.register_algorithm(Algorithm::Saturnin, || {
122        Ok(Box::new(SaturninAead::new()) as Box<dyn AeadWithMetadata>)
123    });
124
125    #[cfg(feature = "shake256")]
126    let _ = registry.register_algorithm(Algorithm::Shake256Aead, || {
127        Ok(Box::new(Shake256Aead::new()) as Box<dyn AeadWithMetadata>)
128    });
129
130    #[cfg(feature = "duplex-sponge-aead")]
131    let _ = registry.register_algorithm(Algorithm::DuplexSpongeAead, || {
132        Ok(Box::new(DuplexSpongeAead::new()) as Box<dyn AeadWithMetadata>)
133    });
134
135    #[cfg(feature = "tweak-aead")]
136    let _ = registry.register_algorithm(Algorithm::TweakAead, || {
137        Ok(Box::new(TweakAead::new()) as Box<dyn AeadWithMetadata>)
138    });
139
140    #[cfg(feature = "romulus-n")]
141    let _ = registry.register_algorithm(Algorithm::RomulusN, || {
142        Ok(Box::new(RomulusNAead::new()) as Box<dyn AeadWithMetadata>)
143    });
144
145    #[cfg(feature = "romulus-m")]
146    let _ = registry.register_algorithm(Algorithm::RomulusM, || {
147        Ok(Box::new(RomulusMAead::new()) as Box<dyn AeadWithMetadata>)
148    });
149
150    #[cfg(feature = "rocca-s")]
151    let _ = registry.register_algorithm(Algorithm::RoccaS, || {
152        Ok(Box::new(RoccaSAead::new()) as Box<dyn AeadWithMetadata>)
153    });
154
155    registry
156});
157
158/// Global AEAD registry instance for no_std environments
159///
160/// This uses thread-safe initialization for WASM and other targets that require Sync.
161/// For true no_std environments without threading, this is still safe.
162#[cfg(not(feature = "std"))]
163static REGISTRY: once_cell::sync::Lazy<AeadRegistry> = once_cell::sync::Lazy::new(|| {
164    let registry = AeadRegistry::new();
165
166    // Register built-in algorithms
167    #[cfg(feature = "saturnin")]
168    let _ = registry.register_algorithm(Algorithm::Saturnin, || {
169        Ok(Box::new(SaturninAead::new()) as Box<dyn AeadWithMetadata>)
170    });
171
172    #[cfg(feature = "shake256")]
173    let _ = registry.register_algorithm(Algorithm::Shake256Aead, || {
174        Ok(Box::new(Shake256Aead::new()) as Box<dyn AeadWithMetadata>)
175    });
176
177    #[cfg(feature = "duplex-sponge-aead")]
178    let _ = registry.register_algorithm(Algorithm::DuplexSpongeAead, || {
179        Ok(Box::new(DuplexSpongeAead::new()) as Box<dyn AeadWithMetadata>)
180    });
181
182    #[cfg(feature = "tweak-aead")]
183    let _ = registry.register_algorithm(Algorithm::TweakAead, || {
184        Ok(Box::new(TweakAead::new()) as Box<dyn AeadWithMetadata>)
185    });
186
187    #[cfg(feature = "romulus-n")]
188    let _ = registry.register_algorithm(Algorithm::RomulusN, || {
189        Ok(Box::new(RomulusNAead::new()) as Box<dyn AeadWithMetadata>)
190    });
191
192    #[cfg(feature = "romulus-m")]
193    let _ = registry.register_algorithm(Algorithm::RomulusM, || {
194        Ok(Box::new(RomulusMAead::new()) as Box<dyn AeadWithMetadata>)
195    });
196
197    #[cfg(feature = "rocca-s")]
198    let _ = registry.register_algorithm(Algorithm::RoccaS, || {
199        Ok(Box::new(RoccaSAead::new()) as Box<dyn AeadWithMetadata>)
200    });
201
202    registry
203});
204
205/// Get the global AEAD registry
206pub fn registry() -> &'static AeadRegistry {
207    &REGISTRY
208}
209
210/// Get available AEAD algorithms
211pub fn available_algorithms() -> Vec<Algorithm> {
212    registry().available_algorithms()
213}
214
215/// Create an AEAD instance by algorithm
216pub fn create_aead(algorithm: Algorithm) -> Result<Box<dyn AeadWithMetadata>> {
217    // Validate algorithm category
218    if algorithm.category() != AlgorithmCategory::Aead {
219        return Err(lib_q_core::Error::InvalidAlgorithm {
220            algorithm: "Algorithm is not an AEAD algorithm",
221        });
222    }
223
224    registry().create_aead(algorithm)
225}
226
227/// Check if an algorithm is available
228pub fn is_algorithm_available(algorithm: Algorithm) -> bool {
229    algorithm.category() == AlgorithmCategory::Aead && registry().is_available(algorithm)
230}
231
232/// Get algorithm metadata
233pub fn get_algorithm_metadata(algorithm: Algorithm) -> Option<&'static AeadMetadata> {
234    if algorithm.category() != AlgorithmCategory::Aead {
235        return None;
236    }
237    registry().get_metadata(algorithm)
238}
239
240/// Register a custom AEAD algorithm
241#[cfg(feature = "std")]
242pub fn register_algorithm<F>(_algorithm: Algorithm, _constructor: F) -> Result<()>
243where
244    F: Fn() -> Result<Box<dyn AeadWithMetadata>> + Send + Sync + 'static,
245{
246    // For std, we need to modify the registry, but it's immutable
247    // This is a limitation of the current design
248    Err(lib_q_core::Error::NotImplemented {
249        feature: "Dynamic algorithm registration requires mutable registry".to_string(),
250    })
251}
252
253/// Register a custom AEAD algorithm for no_std - using safe approach
254#[cfg(not(feature = "std"))]
255pub fn register_algorithm<F>(algorithm: Algorithm, constructor: F) -> Result<()>
256where
257    F: Fn() -> Result<Box<dyn AeadWithMetadata>> + Send + Sync + 'static,
258{
259    if algorithm.category() != AlgorithmCategory::Aead {
260        return Err(lib_q_core::Error::InvalidAlgorithm {
261            algorithm: "Algorithm is not an AEAD algorithm",
262        });
263    }
264
265    // Use the registry's safe registration method
266    // Note: This will only work if the registry hasn't been initialized yet
267    // In a real implementation, you might want to use a different approach
268    // such as a global mutex or atomic operations
269    registry().register_algorithm(algorithm, constructor)
270}
271
272/// Register a plugin
273#[cfg(feature = "std")]
274pub fn register_plugin(_plugin: Box<dyn AeadPlugin>) -> Result<()> {
275    // For std, we need to modify the registry, but it's immutable
276    // This is a limitation of the current design
277    Err(lib_q_core::Error::NotImplemented {
278        feature: "Dynamic plugin registration requires mutable registry".to_string(),
279    })
280}
281
282/// Register a plugin for no_std - using safe approach
283#[cfg(not(feature = "std"))]
284pub fn register_plugin(plugin: Box<dyn AeadPlugin>) -> Result<()> {
285    // Use the registry's safe registration method
286    registry().register_plugin(plugin)
287}
288
289#[cfg(test)]
290mod tests {
291    use super::*;
292
293    #[test]
294    fn test_available_algorithms() {
295        let algorithms = available_algorithms();
296        assert!(!algorithms.is_empty());
297
298        // All returned algorithms should be AEAD algorithms
299        for algorithm in algorithms {
300            assert_eq!(algorithm.category(), AlgorithmCategory::Aead);
301        }
302    }
303
304    #[test]
305    fn test_create_aead() {
306        let algorithms = available_algorithms();
307
308        for algorithm in algorithms {
309            let aead = create_aead(algorithm);
310            assert!(aead.is_ok(), "Failed to create AEAD for {:?}", algorithm);
311        }
312    }
313
314    #[test]
315    fn test_invalid_algorithm() {
316        // Try to create AEAD with non-AEAD algorithm
317        let result = create_aead(Algorithm::MlKem512);
318        assert!(result.is_err());
319
320        if let Err(lib_q_core::Error::InvalidAlgorithm { algorithm }) = result {
321            assert!(algorithm.contains("not an AEAD algorithm"));
322        } else {
323            panic!("Expected InvalidAlgorithm error");
324        }
325    }
326
327    #[test]
328    fn test_algorithm_availability() {
329        let algorithms = available_algorithms();
330
331        for algorithm in algorithms {
332            assert!(is_algorithm_available(algorithm));
333        }
334
335        // Non-AEAD algorithms should not be available
336        assert!(!is_algorithm_available(Algorithm::MlKem512));
337    }
338
339    #[test]
340    fn test_algorithm_metadata() {
341        let algorithms = available_algorithms();
342
343        for algorithm in algorithms {
344            let metadata = get_algorithm_metadata(algorithm);
345            assert!(metadata.is_some(), "No metadata for {:?}", algorithm);
346
347            if let Some(meta) = metadata {
348                assert_eq!(meta.algorithm, algorithm);
349                assert!(meta.key_size > 0);
350                assert!(meta.nonce_size > 0);
351                assert!(meta.tag_size > 0);
352            }
353        }
354    }
355
356    #[test]
357    fn test_security_config_roundtrip() {
358        let orig = get_security_config();
359        set_security_config(orig);
360        assert_eq!(get_security_config(), orig);
361    }
362
363    #[test]
364    fn test_security_context_new() {
365        let _ctx = SecurityContext::new();
366    }
367}
lib_q_aead/lib.rs

lib_q_aead/
lib.rs
