bc_components/mlkem/
mlkem_ciphertext.rs

1use anyhow::{Result, anyhow};
2use dcbor::prelude::*;
3use pqcrypto_mlkem::*;
4use pqcrypto_traits::kem::Ciphertext;
5
6use super::MLKEM;
7use crate::tags;
8
9/// A ciphertext containing an encapsulated shared secret for ML-KEM.
10///
11/// `MLKEMCiphertext` represents a ciphertext produced by the ML-KEM
12/// (Module Lattice-based Key Encapsulation Mechanism) post-quantum algorithm
13/// during the encapsulation process. It contains an encapsulated shared secret
14/// that can only be recovered by the corresponding private key.
15///
16/// It supports multiple security levels through the variants:
17///
18/// - `MLKEM512`: NIST security level 1 (roughly equivalent to AES-128), 768
19///   bytes
20/// - `MLKEM768`: NIST security level 3 (roughly equivalent to AES-192), 1088
21///   bytes
22/// - `MLKEM1024`: NIST security level 5 (roughly equivalent to AES-256), 1568
23///   bytes
24///
25/// # Examples
26///
27/// ```
28/// use bc_components::MLKEM;
29///
30/// // Generate a keypair
31/// let (private_key, public_key) = MLKEM::MLKEM512.keypair();
32///
33/// // Encapsulate a shared secret using the public key
34/// let (shared_secret_a, ciphertext) =
35///     public_key.encapsulate_new_shared_secret();
36///
37/// // Decapsulate the shared secret using the private key
38/// let shared_secret_b =
39///     private_key.decapsulate_shared_secret(&ciphertext).unwrap();
40///
41/// // Both shared secrets should be the same
42/// assert_eq!(shared_secret_a, shared_secret_b);
43/// ```
44#[derive(Clone, PartialEq)]
45pub enum MLKEMCiphertext {
46    /// An ML-KEM-512 ciphertext (NIST security level 1)
47    MLKEM512(Box<mlkem512::Ciphertext>),
48    /// An ML-KEM-768 ciphertext (NIST security level 3)
49    MLKEM768(Box<mlkem768::Ciphertext>),
50    /// An ML-KEM-1024 ciphertext (NIST security level 5)
51    MLKEM1024(Box<mlkem1024::Ciphertext>),
52}
53
54impl MLKEMCiphertext {
55    /// Returns the security level of this ML-KEM ciphertext.
56    pub fn level(&self) -> MLKEM {
57        match self {
58            MLKEMCiphertext::MLKEM512(_) => MLKEM::MLKEM512,
59            MLKEMCiphertext::MLKEM768(_) => MLKEM::MLKEM768,
60            MLKEMCiphertext::MLKEM1024(_) => MLKEM::MLKEM1024,
61        }
62    }
63
64    /// Returns the size of this ML-KEM ciphertext in bytes.
65    pub fn size(&self) -> usize { self.level().ciphertext_size() }
66
67    /// Returns the raw bytes of this ML-KEM ciphertext.
68    pub fn as_bytes(&self) -> &[u8] { self.as_ref() }
69
70    /// Creates an ML-KEM ciphertext from raw bytes and a security level.
71    ///
72    /// # Parameters
73    ///
74    /// * `level` - The security level of the ciphertext.
75    /// * `bytes` - The raw bytes of the ciphertext.
76    ///
77    /// # Returns
78    ///
79    /// An `MLKEMCiphertext` if the bytes represent a valid ciphertext for the
80    /// given level, or an error otherwise.
81    ///
82    /// # Errors
83    ///
84    /// Returns an error if the bytes do not represent a valid ML-KEM ciphertext
85    /// for the specified security level.
86    pub fn from_bytes(level: MLKEM, bytes: &[u8]) -> Result<Self> {
87        match level {
88            MLKEM::MLKEM512 => Ok(MLKEMCiphertext::MLKEM512(Box::new(
89                mlkem512::Ciphertext::from_bytes(bytes)
90                    .map_err(|e| anyhow!(e))?,
91            ))),
92            MLKEM::MLKEM768 => Ok(MLKEMCiphertext::MLKEM768(Box::new(
93                mlkem768::Ciphertext::from_bytes(bytes)
94                    .map_err(|e| anyhow!(e))?,
95            ))),
96            MLKEM::MLKEM1024 => Ok(MLKEMCiphertext::MLKEM1024(Box::new(
97                mlkem1024::Ciphertext::from_bytes(bytes)
98                    .map_err(|e| anyhow!(e))?,
99            ))),
100        }
101    }
102}
103
104impl AsRef<[u8]> for MLKEMCiphertext {
105    /// Returns the raw bytes of the ciphertext.
106    fn as_ref(&self) -> &[u8] {
107        match self {
108            MLKEMCiphertext::MLKEM512(ct) => ct.as_ref().as_bytes(),
109            MLKEMCiphertext::MLKEM768(ct) => ct.as_ref().as_bytes(),
110            MLKEMCiphertext::MLKEM1024(ct) => ct.as_ref().as_bytes(),
111        }
112    }
113}
114
115/// Provides debug formatting for ML-KEM ciphertexts.
116impl std::fmt::Debug for MLKEMCiphertext {
117    /// Formats the ciphertext as a string for debugging purposes.
118    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
119        match self {
120            MLKEMCiphertext::MLKEM512(_) => f.write_str("MLKEM512Ciphertext"),
121            MLKEMCiphertext::MLKEM768(_) => f.write_str("MLKEM768Ciphertext"),
122            MLKEMCiphertext::MLKEM1024(_) => f.write_str("MLKEM1024Ciphertext"),
123        }
124    }
125}
126
127/// Defines CBOR tags for ML-KEM ciphertexts.
128impl CBORTagged for MLKEMCiphertext {
129    /// Returns the CBOR tag for ML-KEM ciphertexts.
130    fn cbor_tags() -> Vec<Tag> {
131        tags_for_values(&[tags::TAG_MLKEM_CIPHERTEXT])
132    }
133}
134
135/// Converts an `MLKEMCiphertext` to CBOR.
136impl From<MLKEMCiphertext> for CBOR {
137    /// Converts to tagged CBOR.
138    fn from(value: MLKEMCiphertext) -> Self { value.tagged_cbor() }
139}
140
141/// Implements CBOR encoding for ML-KEM ciphertexts.
142impl CBORTaggedEncodable for MLKEMCiphertext {
143    /// Creates the untagged CBOR representation as an array with level and
144    /// ciphertext bytes.
145    fn untagged_cbor(&self) -> CBOR {
146        vec![self.level().into(), CBOR::to_byte_string(self.as_bytes())].into()
147    }
148}
149
150/// Attempts to convert CBOR to an `MLKEMCiphertext`.
151impl TryFrom<CBOR> for MLKEMCiphertext {
152    type Error = dcbor::Error;
153
154    /// Converts from tagged CBOR.
155    fn try_from(cbor: CBOR) -> dcbor::Result<Self> {
156        Self::from_tagged_cbor(cbor)
157    }
158}
159
160/// Implements CBOR decoding for ML-KEM ciphertexts.
161impl CBORTaggedDecodable for MLKEMCiphertext {
162    /// Creates an `MLKEMCiphertext` from untagged CBOR.
163    ///
164    /// # Errors
165    /// Returns an error if the CBOR value doesn't represent a valid ML-KEM
166    /// ciphertext.
167    fn from_untagged_cbor(untagged_cbor: CBOR) -> dcbor::Result<Self> {
168        match untagged_cbor.as_case() {
169            CBORCase::Array(elements) => {
170                if elements.len() != 2 {
171                    return Err("MLKEMCiphertext must have two elements".into());
172                }
173
174                let level = MLKEM::try_from(elements[0].clone())?;
175                let data = CBOR::try_into_byte_string(elements[1].clone())?;
176                Ok(MLKEMCiphertext::from_bytes(level, &data)?)
177            }
178            _ => Err("MLKEMCiphertext must be an array".into()),
179        }
180    }
181}
bc_components/mlkem/mlkem_ciphertext.rs

bc_components/mlkem/
mlkem_ciphertext.rs
