lib_q_core/providers/
kem_provider.rs

1//! KEM (Key Encapsulation Mechanism) provider implementation
2//!
3//! This module provides the LibQKemProvider that implements KEM operations
4//! with proper security validation and algorithm routing.
5
6#[cfg(feature = "alloc")]
7use alloc::{
8    string::ToString,
9    vec::Vec,
10};
11
12use crate::api::{
13    Algorithm,
14    KemOperations,
15};
16use crate::error::Result;
17use crate::security::SecurityValidator;
18use crate::traits::{
19    KemKeypair,
20    KemPublicKey,
21    KemSecretKey,
22};
23
24/// lib-Q KEM provider implementation
25///
26/// This provider implements KEM operations for lib-Q, including key generation,
27/// encapsulation, and decapsulation with proper security validation.
28#[cfg(feature = "alloc")]
29#[derive(Clone)]
30pub struct LibQKemProvider {
31    security_validator: SecurityValidator,
32}
33
34#[cfg(feature = "alloc")]
35impl LibQKemProvider {
36    /// Create a new KEM provider
37    ///
38    /// # Returns
39    ///
40    /// A new instance of LibQKemProvider with security validation initialized.
41    ///
42    /// # Errors
43    ///
44    /// Returns an error if the security validator fails to initialize.
45    pub fn new() -> Result<Self> {
46        Ok(Self {
47            security_validator: SecurityValidator::new()?,
48        })
49    }
50}
51
52#[cfg(feature = "alloc")]
53impl KemOperations for LibQKemProvider {
54    fn generate_keypair(
55        &self,
56        algorithm: Algorithm,
57        randomness: Option<&[u8]>,
58    ) -> Result<KemKeypair> {
59        // Validate algorithm category
60        self.security_validator
61            .validate_algorithm_category(algorithm, crate::api::AlgorithmCategory::Kem)?;
62
63        // Validate randomness if provided
64        if let Some(rng) = randomness {
65            self.security_validator.validate_randomness(rng)?;
66        }
67
68        // Route to specific algorithm implementation
69        // Note: Actual implementations are provided by the main lib-q crate
70        match algorithm {
71            Algorithm::MlKem512 | Algorithm::MlKem768 | Algorithm::MlKem1024 => {
72                Err(crate::error::Error::NotImplemented {
73                    feature: "ML-KEM implementations are provided by the main lib-q crate"
74                        .to_string(),
75                })
76            }
77            Algorithm::Hqc128 | Algorithm::Hqc192 | Algorithm::Hqc256 => {
78                Err(crate::error::Error::NotImplemented {
79                    feature: "HQC implementations are provided by the main lib-q crate".to_string(),
80                })
81            }
82            _ => Err(crate::error::Error::InvalidAlgorithm {
83                algorithm: "Algorithm not supported for KEM operations",
84            }),
85        }
86    }
87
88    fn encapsulate(
89        &self,
90        algorithm: Algorithm,
91        public_key: &KemPublicKey,
92        randomness: Option<&[u8]>,
93    ) -> Result<(Vec<u8>, Vec<u8>)> {
94        // Validate algorithm category
95        self.security_validator
96            .validate_algorithm_category(algorithm, crate::api::AlgorithmCategory::Kem)?;
97
98        // Validate public key
99        self.security_validator
100            .validate_public_key(algorithm, public_key.as_bytes())?;
101
102        // Validate randomness if provided
103        if let Some(rng) = randomness {
104            self.security_validator.validate_randomness(rng)?;
105        }
106
107        // Route to specific algorithm implementation
108        // Note: Actual implementations are provided by the main lib-q crate
109        match algorithm {
110            Algorithm::MlKem512 | Algorithm::MlKem768 | Algorithm::MlKem1024 => {
111                Err(crate::error::Error::NotImplemented {
112                    feature: "ML-KEM implementations are provided by the main lib-q crate"
113                        .to_string(),
114                })
115            }
116            Algorithm::Hqc128 | Algorithm::Hqc192 | Algorithm::Hqc256 => {
117                Err(crate::error::Error::NotImplemented {
118                    feature: "HQC implementations are provided by the main lib-q crate".to_string(),
119                })
120            }
121            _ => Err(crate::error::Error::InvalidAlgorithm {
122                algorithm: "Algorithm not supported for KEM operations",
123            }),
124        }
125    }
126
127    fn decapsulate(
128        &self,
129        algorithm: Algorithm,
130        secret_key: &KemSecretKey,
131        ciphertext: &[u8],
132    ) -> Result<Vec<u8>> {
133        // Validate algorithm category
134        self.security_validator
135            .validate_algorithm_category(algorithm, crate::api::AlgorithmCategory::Kem)?;
136
137        // Validate secret key
138        self.security_validator
139            .validate_secret_key(algorithm, secret_key.as_bytes())?;
140
141        // Validate ciphertext
142        self.security_validator
143            .validate_ciphertext(algorithm, ciphertext)?;
144
145        // Route to specific algorithm implementation
146        // Note: Actual implementations are provided by the main lib-q crate
147        match algorithm {
148            Algorithm::MlKem512 | Algorithm::MlKem768 | Algorithm::MlKem1024 => {
149                Err(crate::error::Error::NotImplemented {
150                    feature: "ML-KEM implementations are provided by the main lib-q crate"
151                        .to_string(),
152                })
153            }
154            Algorithm::Hqc128 | Algorithm::Hqc192 | Algorithm::Hqc256 => {
155                Err(crate::error::Error::NotImplemented {
156                    feature: "HQC implementations are provided by the main lib-q crate".to_string(),
157                })
158            }
159            _ => Err(crate::error::Error::InvalidAlgorithm {
160                algorithm: "Algorithm not supported for KEM operations",
161            }),
162        }
163    }
164
165    fn derive_public_key(
166        &self,
167        algorithm: Algorithm,
168        secret_key: &KemSecretKey,
169    ) -> Result<KemPublicKey> {
170        // Validate algorithm category
171        self.security_validator
172            .validate_algorithm_category(algorithm, crate::api::AlgorithmCategory::Kem)?;
173
174        // Validate secret key
175        self.security_validator
176            .validate_secret_key(algorithm, secret_key.as_bytes())?;
177
178        // Route to specific algorithm implementation
179        // Note: Actual implementations are provided by the main lib-q crate
180        match algorithm {
181            Algorithm::MlKem512 | Algorithm::MlKem768 | Algorithm::MlKem1024 => {
182                Err(crate::error::Error::NotImplemented {
183                    feature: "ML-KEM implementations are provided by the main lib-q crate"
184                        .to_string(),
185                })
186            }
187            Algorithm::Hqc128 | Algorithm::Hqc192 | Algorithm::Hqc256 => {
188                Err(crate::error::Error::NotImplemented {
189                    feature: "HQC implementations are provided by the main lib-q crate".to_string(),
190                })
191            }
192            _ => Err(crate::error::Error::InvalidAlgorithm {
193                algorithm: "Algorithm not supported for KEM operations",
194            }),
195        }
196    }
197}
198
199#[cfg(test)]
200#[cfg(feature = "alloc")]
201mod tests {
202    use super::*;
203
204    #[test]
205    fn test_kem_provider_creation() {
206        let provider = LibQKemProvider::new();
207        assert!(
208            provider.is_ok(),
209            "LibQKemProvider should be created successfully"
210        );
211    }
212
213    #[test]
214    fn test_kem_provider_unsupported_algorithm() {
215        let provider = LibQKemProvider::new().unwrap();
216        let result = provider.generate_keypair(Algorithm::Sha3_256, None);
217        assert!(
218            result.is_err(),
219            "Should return error for unsupported algorithm"
220        );
221
222        if let Err(crate::error::Error::InvalidAlgorithm { .. }) = result {
223            // Expected error type
224        } else {
225            panic!("Expected InvalidAlgorithm error");
226        }
227    }
228
229    #[test]
230    fn test_kem_provider_feature_flag_handling() {
231        let provider = LibQKemProvider::new().unwrap();
232
233        // Test ML-KEM without feature flag
234        let result = provider.generate_keypair(Algorithm::MlKem512, None);
235        assert!(
236            result.is_err(),
237            "Should return error when feature flag is not enabled"
238        );
239
240        if let Err(crate::error::Error::NotImplemented { feature }) = result {
241            assert!(
242                feature.contains("ML-KEM implementations are provided by the main lib-q crate"),
243                "Error should mention that implementations are provided by main lib-q crate"
244            );
245        } else {
246            panic!("Expected NotImplemented error");
247        }
248    }
249}
lib_q_core/providers/kem_provider.rs

lib_q_core/providers/
kem_provider.rs
