bc_components/mldsa/
mldsa_public_key.rs

1use anyhow::{Result, anyhow, bail};
2use dcbor::prelude::*;
3use pqcrypto_mldsa::*;
4use pqcrypto_traits::sign::*;
5
6use super::{MLDSA, MLDSASignature};
7use crate::tags;
8
9/// A public key for the ML-DSA post-quantum digital signature algorithm.
10///
11/// `MLDSAPublicKey` represents a public key that can be used to verify digital
12/// signatures created with the ML-DSA (Module Lattice-based Digital Signature
13/// Algorithm) post-quantum algorithm. It supports multiple security levels
14/// through the variants:
15///
16/// - `MLDSA44`: NIST security level 2 (roughly equivalent to AES-128)
17/// - `MLDSA65`: NIST security level 3 (roughly equivalent to AES-192)
18/// - `MLDSA87`: NIST security level 5 (roughly equivalent to AES-256)
19///
20/// # Examples
21///
22/// ```
23/// use bc_components::MLDSA;
24///
25/// // Generate a keypair
26/// let (private_key, public_key) = MLDSA::MLDSA44.keypair();
27///
28/// // Sign a message
29/// let message = b"Hello, post-quantum world!";
30/// let signature = private_key.sign(message);
31///
32/// // Verify the signature
33/// assert!(public_key.verify(&signature, message).unwrap());
34/// ```
35#[derive(Clone)]
36pub enum MLDSAPublicKey {
37    /// An ML-DSA44 public key (NIST security level 2)
38    MLDSA44(Box<mldsa44::PublicKey>),
39    /// An ML-DSA65 public key (NIST security level 3)
40    MLDSA65(Box<mldsa65::PublicKey>),
41    /// An ML-DSA87 public key (NIST security level 5)
42    MLDSA87(Box<mldsa87::PublicKey>),
43}
44
45/// Implements equality comparison for ML-DSA public keys.
46impl PartialEq for MLDSAPublicKey {
47    /// Compares two ML-DSA public keys for equality.
48    ///
49    /// Two ML-DSA public keys are equal if they have the same security level
50    /// and the same raw byte representation.
51    fn eq(&self, other: &Self) -> bool {
52        self.level() == other.level() && self.as_bytes() == other.as_bytes()
53    }
54}
55
56impl Eq for MLDSAPublicKey {}
57
58/// Implements hashing for ML-DSA public keys.
59impl std::hash::Hash for MLDSAPublicKey {
60    /// Hashes both the security level and the raw bytes of the public key.
61    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
62        self.level().hash(state);
63        self.as_bytes().hash(state);
64    }
65}
66
67impl MLDSAPublicKey {
68    /// Verifies an ML-DSA signature for a message using this public key.
69    ///
70    /// # Parameters
71    ///
72    /// * `signature` - The signature to verify.
73    /// * `message` - The message that was signed.
74    ///
75    /// # Returns
76    ///
77    /// `Ok(true)` if the signature is valid for the message and this public
78    /// key, `Ok(false)` if the signature is invalid, or an error if the
79    /// security levels of the signature and public key don't match.
80    ///
81    /// # Errors
82    ///
83    /// Returns an error if the security level of the signature doesn't match
84    /// the security level of this public key.
85    ///
86    /// # Examples
87    ///
88    /// ```
89    /// use bc_components::MLDSA;
90    ///
91    /// let (private_key, public_key) = MLDSA::MLDSA44.keypair();
92    /// let message = b"Hello, world!";
93    /// let signature = private_key.sign(message);
94    ///
95    /// assert!(public_key.verify(&signature, message).unwrap());
96    /// ```
97    pub fn verify(
98        &self,
99        signature: &MLDSASignature,
100        message: impl AsRef<[u8]>,
101    ) -> Result<bool> {
102        if signature.level() != self.level() {
103            bail!("Signature level does not match public key level");
104        }
105
106        let verifies = match (self, signature) {
107            (MLDSAPublicKey::MLDSA44(pk), MLDSASignature::MLDSA44(sig)) => {
108                mldsa44::verify_detached_signature(sig, message.as_ref(), pk)
109                    .is_ok()
110            }
111            (MLDSAPublicKey::MLDSA65(pk), MLDSASignature::MLDSA65(sig)) => {
112                mldsa65::verify_detached_signature(sig, message.as_ref(), pk)
113                    .is_ok()
114            }
115            (MLDSAPublicKey::MLDSA87(pk), MLDSASignature::MLDSA87(sig)) => {
116                mldsa87::verify_detached_signature(sig, message.as_ref(), pk)
117                    .is_ok()
118            }
119            _ => false,
120        };
121
122        Ok(verifies)
123    }
124
125    /// Returns the security level of this ML-DSA public key.
126    pub fn level(&self) -> MLDSA {
127        match self {
128            MLDSAPublicKey::MLDSA44(_) => MLDSA::MLDSA44,
129            MLDSAPublicKey::MLDSA65(_) => MLDSA::MLDSA65,
130            MLDSAPublicKey::MLDSA87(_) => MLDSA::MLDSA87,
131        }
132    }
133
134    /// Returns the size of this ML-DSA public key in bytes.
135    pub fn size(&self) -> usize { self.level().public_key_size() }
136
137    /// Returns the raw bytes of this ML-DSA public key.
138    pub fn as_bytes(&self) -> &[u8] { self.as_ref() }
139
140    /// Creates an ML-DSA public key from raw bytes and a security level.
141    ///
142    /// # Parameters
143    ///
144    /// * `level` - The security level of the key.
145    /// * `bytes` - The raw bytes of the key.
146    ///
147    /// # Returns
148    ///
149    /// An `MLDSAPublicKey` if the bytes represent a valid key for the given
150    /// level, or an error otherwise.
151    ///
152    /// # Errors
153    ///
154    /// Returns an error if the bytes do not represent a valid ML-DSA public key
155    /// for the specified security level.
156    pub fn from_bytes(level: MLDSA, bytes: &[u8]) -> Result<Self> {
157        match level {
158            MLDSA::MLDSA44 => Ok(MLDSAPublicKey::MLDSA44(Box::new(
159                mldsa44::PublicKey::from_bytes(bytes)
160                    .map_err(|e| anyhow!(e))?,
161            ))),
162            MLDSA::MLDSA65 => Ok(MLDSAPublicKey::MLDSA65(Box::new(
163                mldsa65::PublicKey::from_bytes(bytes)
164                    .map_err(|e| anyhow!(e))?,
165            ))),
166            MLDSA::MLDSA87 => Ok(MLDSAPublicKey::MLDSA87(Box::new(
167                mldsa87::PublicKey::from_bytes(bytes)
168                    .map_err(|e| anyhow!(e))?,
169            ))),
170        }
171    }
172}
173
174impl AsRef<[u8]> for MLDSAPublicKey {
175    /// Returns the public key as a byte slice.
176    fn as_ref(&self) -> &[u8] {
177        match self {
178            MLDSAPublicKey::MLDSA44(key) => key.as_bytes(),
179            MLDSAPublicKey::MLDSA65(key) => key.as_bytes(),
180            MLDSAPublicKey::MLDSA87(key) => key.as_bytes(),
181        }
182    }
183}
184
185/// Provides debug formatting for ML-DSA public keys.
186impl std::fmt::Debug for MLDSAPublicKey {
187    /// Formats the public key as a string for debugging purposes.
188    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
189        match self {
190            MLDSAPublicKey::MLDSA44(_) => f.write_str("MLDSA442PublicKey"),
191            MLDSAPublicKey::MLDSA65(_) => f.write_str("MLDSA65PublicKey"),
192            MLDSAPublicKey::MLDSA87(_) => f.write_str("MLDSA87PublicKey"),
193        }
194    }
195}
196
197/// Defines CBOR tags for ML-DSA public keys.
198impl CBORTagged for MLDSAPublicKey {
199    /// Returns the CBOR tag for ML-DSA public keys.
200    fn cbor_tags() -> Vec<Tag> {
201        tags_for_values(&[tags::TAG_MLDSA_PUBLIC_KEY])
202    }
203}
204
205/// Converts an `MLDSAPublicKey` to CBOR.
206impl From<MLDSAPublicKey> for CBOR {
207    /// Converts to tagged CBOR.
208    fn from(value: MLDSAPublicKey) -> Self { value.tagged_cbor() }
209}
210
211/// Implements CBOR encoding for ML-DSA public keys.
212impl CBORTaggedEncodable for MLDSAPublicKey {
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 `MLDSAPublicKey`.
221impl TryFrom<CBOR> for MLDSAPublicKey {
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-DSA public keys.
231impl CBORTaggedDecodable for MLDSAPublicKey {
232    /// Creates an `MLDSAPublicKey` from untagged CBOR.
233    ///
234    /// # Errors
235    /// Returns an error if the CBOR value doesn't represent a valid ML-DSA
236    /// public 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("MLDSAPublicKey must have two elements".into());
242                }
243
244                let level = MLDSA::try_from(elements[0].clone())?;
245                let data = CBOR::try_into_byte_string(elements[1].clone())?;
246                Ok(MLDSAPublicKey::from_bytes(level, &data)?)
247            }
248            _ => Err("MLDSAPublicKey must be an array".into()),
249        }
250    }
251}
bc_components/mldsa/mldsa_public_key.rs

bc_components/mldsa/
mldsa_public_key.rs
