bc_components/mlkem/
mlkem_private_key.rs

1use dcbor::prelude::*;
2use pqcrypto_mlkem::*;
3use pqcrypto_traits::kem::{SecretKey, SharedSecret};
4
5use super::{MLKEM, MLKEMCiphertext};
6use crate::{
7    Decrypter, EncapsulationPrivateKey, Error, Result, SymmetricKey, tags,
8};
9
10/// A private key for the ML-KEM post-quantum key encapsulation mechanism.
11///
12/// `MLKEMPrivateKey` represents a private key that can be used to decapsulate
13/// shared secrets using the ML-KEM (Module Lattice-based Key Encapsulation
14/// Mechanism) post-quantum algorithm. It supports multiple security levels
15/// through the variants:
16///
17/// - `MLKEM512`: NIST security level 1 (roughly equivalent to AES-128), 1632
18///   bytes
19/// - `MLKEM768`: NIST security level 3 (roughly equivalent to AES-192), 2400
20///   bytes
21/// - `MLKEM1024`: NIST security level 5 (roughly equivalent to AES-256), 3168
22///   bytes
23///
24/// # Security
25///
26/// ML-KEM private keys should be kept secure and never exposed. They provide
27/// resistance against attacks from both classical and quantum computers.
28///
29/// # Examples
30///
31/// ```
32/// use bc_components::MLKEM;
33///
34/// // Generate a keypair
35/// let (private_key, public_key) = MLKEM::MLKEM512.keypair();
36///
37/// // Party A encapsulates a shared secret using the public key
38/// let (shared_secret_a, ciphertext) = public_key.encapsulate_new_shared_secret();
39///
40/// // Party B decapsulates the shared secret using the private key and ciphertext
41/// let shared_secret_b = private_key.decapsulate_shared_secret(&ciphertext).unwrap();
42///
43/// // Both parties now have the same shared secret
44/// assert_eq!(shared_secret_a, shared_secret_b);
45/// ```
46#[derive(Clone, PartialEq)]
47pub enum MLKEMPrivateKey {
48    /// An ML-KEM-512 private key (NIST security level 1)
49    MLKEM512(Box<mlkem512::SecretKey>),
50    /// An ML-KEM-768 private key (NIST security level 3)
51    MLKEM768(Box<mlkem768::SecretKey>),
52    /// An ML-KEM-1024 private key (NIST security level 5)
53    MLKEM1024(Box<mlkem1024::SecretKey>),
54}
55
56impl Eq for MLKEMPrivateKey {}
57
58/// Implements hashing for ML-KEM private keys.
59impl std::hash::Hash for MLKEMPrivateKey {
60    /// Hashes the raw bytes of the private key.
61    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
62        match self {
63            MLKEMPrivateKey::MLKEM512(sk) => sk.as_bytes().hash(state),
64            MLKEMPrivateKey::MLKEM768(sk) => sk.as_bytes().hash(state),
65            MLKEMPrivateKey::MLKEM1024(sk) => sk.as_bytes().hash(state),
66        }
67    }
68}
69
70impl MLKEMPrivateKey {
71    /// Returns the security level of this ML-KEM private key.
72    pub fn level(&self) -> MLKEM {
73        match self {
74            MLKEMPrivateKey::MLKEM512(_) => MLKEM::MLKEM512,
75            MLKEMPrivateKey::MLKEM768(_) => MLKEM::MLKEM768,
76            MLKEMPrivateKey::MLKEM1024(_) => MLKEM::MLKEM1024,
77        }
78    }
79
80    /// Returns the size of this ML-KEM private key in bytes.
81    pub fn size(&self) -> usize { self.level().private_key_size() }
82
83    /// Returns the raw bytes of this ML-KEM private key.
84    pub fn as_bytes(&self) -> &[u8] { self.as_ref() }
85
86    /// Creates an ML-KEM private key from raw bytes and a security level.
87    ///
88    /// # Parameters
89    ///
90    /// * `level` - The security level of the key.
91    /// * `bytes` - The raw bytes of the key.
92    ///
93    /// # Returns
94    ///
95    /// An `MLKEMPrivateKey` if the bytes represent a valid key for the given
96    /// level, or an error otherwise.
97    ///
98    /// # Errors
99    ///
100    /// Returns an error if the bytes do not represent a valid ML-KEM private
101    /// key for the specified security level.
102    pub fn from_bytes(level: MLKEM, bytes: &[u8]) -> Result<Self> {
103        match level {
104            MLKEM::MLKEM512 => Ok(MLKEMPrivateKey::MLKEM512(Box::new(
105                mlkem512::SecretKey::from_bytes(bytes)
106                    .map_err(|e| Error::post_quantum(e.to_string()))?,
107            ))),
108            MLKEM::MLKEM768 => Ok(MLKEMPrivateKey::MLKEM768(Box::new(
109                mlkem768::SecretKey::from_bytes(bytes)
110                    .map_err(|e| Error::post_quantum(e.to_string()))?,
111            ))),
112            MLKEM::MLKEM1024 => Ok(MLKEMPrivateKey::MLKEM1024(Box::new(
113                mlkem1024::SecretKey::from_bytes(bytes)
114                    .map_err(|e| Error::post_quantum(e.to_string()))?,
115            ))),
116        }
117    }
118
119    /// Decapsulates a shared secret from a ciphertext using this private key.
120    ///
121    /// # Parameters
122    ///
123    /// * `ciphertext` - The ciphertext containing the encapsulated shared
124    ///   secret.
125    ///
126    /// # Returns
127    ///
128    /// A `SymmetricKey` containing the decapsulated shared secret, or an error
129    /// if decapsulation fails.
130    ///
131    /// # Errors
132    ///
133    /// Returns an error if the security level of the ciphertext doesn't match
134    /// the security level of this private key, or if decapsulation fails
135    /// for any other reason.
136    ///
137    /// # Panics
138    ///
139    /// Panics if the security level of the ciphertext doesn't match the
140    /// security level of this private key.
141    pub fn decapsulate_shared_secret(
142        &self,
143        ciphertext: &MLKEMCiphertext,
144    ) -> Result<SymmetricKey> {
145        match (self, ciphertext) {
146            (MLKEMPrivateKey::MLKEM512(sk), MLKEMCiphertext::MLKEM512(ct)) => {
147                let ss = mlkem512::decapsulate(ct.as_ref(), sk.as_ref());
148                SymmetricKey::from_data_ref(ss.as_bytes())
149            }
150            (MLKEMPrivateKey::MLKEM768(sk), MLKEMCiphertext::MLKEM768(ct)) => {
151                let ss = mlkem768::decapsulate(ct.as_ref(), sk.as_ref());
152                SymmetricKey::from_data_ref(ss.as_bytes())
153            }
154            (
155                MLKEMPrivateKey::MLKEM1024(sk),
156                MLKEMCiphertext::MLKEM1024(ct),
157            ) => {
158                let ss = mlkem1024::decapsulate(ct.as_ref(), sk.as_ref());
159                SymmetricKey::from_data_ref(ss.as_bytes())
160            }
161            _ => panic!("MLKEM level mismatch"),
162        }
163    }
164}
165
166impl AsRef<[u8]> for MLKEMPrivateKey {
167    /// Returns the raw bytes of the private key.
168    fn as_ref(&self) -> &[u8] {
169        match self {
170            MLKEMPrivateKey::MLKEM512(sk) => sk.as_ref().as_bytes(),
171            MLKEMPrivateKey::MLKEM768(sk) => sk.as_ref().as_bytes(),
172            MLKEMPrivateKey::MLKEM1024(sk) => sk.as_ref().as_bytes(),
173        }
174    }
175}
176
177/// Implements the `Decrypter` trait for ML-KEM private keys.
178impl Decrypter for MLKEMPrivateKey {
179    /// Returns this key as an `EncapsulationPrivateKey`.
180    fn encapsulation_private_key(&self) -> EncapsulationPrivateKey {
181        EncapsulationPrivateKey::MLKEM(self.clone())
182    }
183}
184
185/// Provides debug formatting for ML-KEM private keys.
186impl std::fmt::Debug for MLKEMPrivateKey {
187    /// Formats the private key as a string for debugging purposes.
188    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
189        match self {
190            MLKEMPrivateKey::MLKEM512(_) => f.write_str("MLKEM512PrivateKey"),
191            MLKEMPrivateKey::MLKEM768(_) => f.write_str("MLKEM768PrivateKey"),
192            MLKEMPrivateKey::MLKEM1024(_) => f.write_str("MLKEM1024PrivateKey"),
193        }
194    }
195}
196
197/// Defines CBOR tags for ML-KEM private keys.
198impl CBORTagged for MLKEMPrivateKey {
199    /// Returns the CBOR tag for ML-KEM private keys.
200    fn cbor_tags() -> Vec<Tag> {
201        tags_for_values(&[tags::TAG_MLKEM_PRIVATE_KEY])
202    }
203}
204
205/// Converts an `MLKEMPrivateKey` to CBOR.
206impl From<MLKEMPrivateKey> for CBOR {
207    /// Converts to tagged CBOR.
208    fn from(value: MLKEMPrivateKey) -> Self { value.tagged_cbor() }
209}
210
211/// Implements CBOR encoding for ML-KEM private keys.
212impl CBORTaggedEncodable for MLKEMPrivateKey {
213    /// Creates the untagged CBOR representation as an array with level and key
214    /// bytes.
215    fn untagged_cbor(&self) -> CBOR {
216        vec![self.level().into(), CBOR::to_byte_string(self.as_bytes())].into()
217    }
218}
219
220/// Attempts to convert CBOR to an `MLKEMPrivateKey`.
221impl TryFrom<CBOR> for MLKEMPrivateKey {
222    type Error = dcbor::Error;
223
224    /// Converts from tagged CBOR.
225    fn try_from(cbor: CBOR) -> dcbor::Result<Self> {
226        Self::from_tagged_cbor(cbor)
227    }
228}
229
230/// Implements CBOR decoding for ML-KEM private keys.
231impl CBORTaggedDecodable for MLKEMPrivateKey {
232    /// Creates an `MLKEMPrivateKey` from untagged CBOR.
233    ///
234    /// # Errors
235    /// Returns an error if the CBOR value doesn't represent a valid ML-KEM
236    /// private key.
237    fn from_untagged_cbor(untagged_cbor: CBOR) -> dcbor::Result<Self> {
238        match untagged_cbor.as_case() {
239            CBORCase::Array(elements) => {
240                if elements.len() != 2 {
241                    return Err("MLKEMPrivateKey must have two elements".into());
242                }
243
244                let level = MLKEM::try_from(elements[0].clone())?;
245                let data = CBOR::try_into_byte_string(elements[1].clone())?;
246                Ok(MLKEMPrivateKey::from_bytes(level, &data)?)
247            }
248            _ => Err("MLKEMPrivateKey must be an array".into()),
249        }
250    }
251}
bc_components/mlkem/mlkem_private_key.rs

bc_components/mlkem/
mlkem_private_key.rs
