bc_components/mlkem/
mlkem_ciphertext.rs

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

bc_components/mlkem/
mlkem_ciphertext.rs
