bc_components/mldsa/mldsa_public_key.rs
1use anyhow::{ anyhow, bail, Result };
2use dcbor::prelude::*;
3use pqcrypto_mldsa::*;
4use pqcrypto_traits::sign::*;
5
6use crate::tags;
7
8use super::{ MLDSASignature, MLDSA };
9
10/// A public key for the ML-DSA post-quantum digital signature algorithm.
11///
12/// `MLDSAPublicKey` represents a public key that can be used to verify digital
13/// signatures created with the ML-DSA (Module Lattice-based Digital Signature Algorithm)
14/// post-quantum algorithm. It supports multiple security levels 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 key,
78 /// `Ok(false)` if the signature is invalid, or an error if the security levels
79 /// 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 the
84 /// 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(&self, signature: &MLDSASignature, message: impl AsRef<[u8]>) -> Result<bool> {
98 if signature.level() != self.level() {
99 bail!("Signature level does not match public key level");
100 }
101
102 let verifies = match (self, signature) {
103 (MLDSAPublicKey::MLDSA44(pk), MLDSASignature::MLDSA44(sig)) => {
104 mldsa44::verify_detached_signature(sig, message.as_ref(), pk).is_ok()
105 }
106 (MLDSAPublicKey::MLDSA65(pk), MLDSASignature::MLDSA65(sig)) => {
107 mldsa65::verify_detached_signature(sig, message.as_ref(), pk).is_ok()
108 }
109 (MLDSAPublicKey::MLDSA87(pk), MLDSASignature::MLDSA87(sig)) => {
110 mldsa87::verify_detached_signature(sig, message.as_ref(), pk).is_ok()
111 }
112 _ => false,
113 };
114
115 Ok(verifies)
116 }
117
118 /// Returns the security level of this ML-DSA public key.
119 pub fn level(&self) -> MLDSA {
120 match self {
121 MLDSAPublicKey::MLDSA44(_) => MLDSA::MLDSA44,
122 MLDSAPublicKey::MLDSA65(_) => MLDSA::MLDSA65,
123 MLDSAPublicKey::MLDSA87(_) => MLDSA::MLDSA87,
124 }
125 }
126
127 /// Returns the size of this ML-DSA public key in bytes.
128 pub fn size(&self) -> usize {
129 self.level().public_key_size()
130 }
131
132 /// Returns the raw bytes of this ML-DSA public key.
133 pub fn as_bytes(&self) -> &[u8] {
134 match self {
135 MLDSAPublicKey::MLDSA44(key) => key.as_bytes(),
136 MLDSAPublicKey::MLDSA65(key) => key.as_bytes(),
137 MLDSAPublicKey::MLDSA87(key) => key.as_bytes(),
138 }
139 }
140
141 /// Creates an ML-DSA public key from raw bytes and a security level.
142 ///
143 /// # Parameters
144 ///
145 /// * `level` - The security level of the key.
146 /// * `bytes` - The raw bytes of the key.
147 ///
148 /// # Returns
149 ///
150 /// An `MLDSAPublicKey` if the bytes represent a valid key for the given level,
151 /// or an error otherwise.
152 ///
153 /// # Errors
154 ///
155 /// Returns an error if the bytes do not represent a valid ML-DSA public key
156 /// for the specified security level.
157 pub fn from_bytes(level: MLDSA, bytes: &[u8]) -> Result<Self> {
158 match level {
159 MLDSA::MLDSA44 =>
160 Ok(
161 MLDSAPublicKey::MLDSA44(
162 Box::new(mldsa44::PublicKey::from_bytes(bytes).map_err(|e| anyhow!(e))?)
163 )
164 ),
165 MLDSA::MLDSA65 =>
166 Ok(
167 MLDSAPublicKey::MLDSA65(
168 Box::new(mldsa65::PublicKey::from_bytes(bytes).map_err(|e| anyhow!(e))?)
169 )
170 ),
171 MLDSA::MLDSA87 =>
172 Ok(
173 MLDSAPublicKey::MLDSA87(
174 Box::new(mldsa87::PublicKey::from_bytes(bytes).map_err(|e| anyhow!(e))?)
175 )
176 ),
177 }
178 }
179}
180
181/// Provides debug formatting for ML-DSA public keys.
182impl std::fmt::Debug for MLDSAPublicKey {
183 /// Formats the public key as a string for debugging purposes.
184 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
185 match self {
186 MLDSAPublicKey::MLDSA44(_) => f.write_str("MLDSA442PublicKey"),
187 MLDSAPublicKey::MLDSA65(_) => f.write_str("MLDSA65PublicKey"),
188 MLDSAPublicKey::MLDSA87(_) => f.write_str("MLDSA87PublicKey"),
189 }
190 }
191}
192
193/// Defines CBOR tags for ML-DSA public keys.
194impl CBORTagged for MLDSAPublicKey {
195 /// Returns the CBOR tag for ML-DSA public keys.
196 fn cbor_tags() -> Vec<Tag> {
197 tags_for_values(&[tags::TAG_MLDSA_PUBLIC_KEY])
198 }
199}
200
201/// Converts an `MLDSAPublicKey` to CBOR.
202impl From<MLDSAPublicKey> for CBOR {
203 /// Converts to tagged CBOR.
204 fn from(value: MLDSAPublicKey) -> Self {
205 value.tagged_cbor()
206 }
207}
208
209/// Implements CBOR encoding for ML-DSA public keys.
210impl CBORTaggedEncodable for MLDSAPublicKey {
211 /// Creates the untagged CBOR representation as an array with level and key bytes.
212 fn untagged_cbor(&self) -> CBOR {
213 vec![self.level().into(), CBOR::to_byte_string(self.as_bytes())].into()
214 }
215}
216
217/// Attempts to convert CBOR to an `MLDSAPublicKey`.
218impl TryFrom<CBOR> for MLDSAPublicKey {
219 type Error = dcbor::Error;
220
221 /// Converts from tagged CBOR.
222 fn try_from(cbor: CBOR) -> dcbor::Result<Self> {
223 Self::from_tagged_cbor(cbor)
224 }
225}
226
227/// Implements CBOR decoding for ML-DSA public keys.
228impl CBORTaggedDecodable for MLDSAPublicKey {
229 /// Creates an `MLDSAPublicKey` from untagged CBOR.
230 ///
231 /// # Errors
232 /// Returns an error if the CBOR value doesn't represent a valid ML-DSA public key.
233 fn from_untagged_cbor(untagged_cbor: CBOR) -> dcbor::Result<Self> {
234 match untagged_cbor.as_case() {
235 CBORCase::Array(elements) => {
236 if elements.len() != 2 {
237 return Err("MLDSAPublicKey must have two elements".into());
238 }
239
240 let level = MLDSA::try_from(elements[0].clone())?;
241 let data = CBOR::try_into_byte_string(elements[1].clone())?;
242 Ok(MLDSAPublicKey::from_bytes(level, &data)?)
243 }
244 _ => {
245 return Err("MLDSAPublicKey must be an array".into());
246 }
247 }
248 }
249}