bc_components/mldsa/
mldsa_signature.rs

1use anyhow::{anyhow, bail, Error, Result};
2use dcbor::prelude::*;
3use pqcrypto_mldsa::*;
4use pqcrypto_traits::sign::*;
5
6use crate::tags;
7
8use super::MLDSA;
9
10/// A digital signature created with the ML-DSA post-quantum signature algorithm.
11///
12/// `MLDSASignature` represents a digital signature created using the ML-DSA
13/// (Module Lattice-based Digital Signature Algorithm) post-quantum algorithm.
14/// 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/// ML-DSA signatures can be verified using the corresponding public key.
21///
22/// # Examples
23///
24/// ```
25/// use bc_components::MLDSA;
26///
27/// // Generate a keypair
28/// let (private_key, public_key) = MLDSA::MLDSA44.keypair();
29///
30/// // Sign a message
31/// let message = b"Hello, post-quantum world!";
32/// let signature = private_key.sign(message);
33///
34/// // Verify the signature
35/// assert!(public_key.verify(&signature, message).unwrap());
36/// ```
37#[derive(Clone)]
38pub enum MLDSASignature {
39    /// An ML-DSA44 signature (NIST security level 2)
40    MLDSA44(Box<mldsa44::DetachedSignature>),
41    /// An ML-DSA65 signature (NIST security level 3)
42    MLDSA65(Box<mldsa65::DetachedSignature>),
43    /// An ML-DSA87 signature (NIST security level 5)
44    MLDSA87(Box<mldsa87::DetachedSignature>),
45}
46
47/// Implements equality comparison for ML-DSA signatures.
48impl PartialEq for MLDSASignature {
49    /// Compares two ML-DSA signatures for equality.
50    ///
51    /// Two ML-DSA signatures are equal if they have the same raw byte representation.
52    fn eq(&self, other: &Self) -> bool {
53        self.as_bytes() == other.as_bytes()
54    }
55}
56
57impl MLDSASignature {
58    /// Returns the security level of this ML-DSA signature.
59    pub fn level(&self) -> MLDSA {
60        match self {
61            MLDSASignature::MLDSA44(_) => MLDSA::MLDSA44,
62            MLDSASignature::MLDSA65(_) => MLDSA::MLDSA65,
63            MLDSASignature::MLDSA87(_) => MLDSA::MLDSA87,
64        }
65    }
66
67    /// Returns the size of this ML-DSA signature in bytes.
68    pub fn size(&self) -> usize {
69        self.level().signature_size()
70    }
71
72    /// Returns the raw bytes of this ML-DSA signature.
73    pub fn as_bytes(&self) -> &[u8] {
74        match self {
75            MLDSASignature::MLDSA44(sig) => sig.as_bytes(),
76            MLDSASignature::MLDSA65(sig) => sig.as_bytes(),
77            MLDSASignature::MLDSA87(sig) => sig.as_bytes(),
78        }
79    }
80
81    /// Creates an ML-DSA signature from raw bytes and a security level.
82    ///
83    /// # Parameters
84    ///
85    /// * `level` - The security level of the signature.
86    /// * `bytes` - The raw bytes of the signature.
87    ///
88    /// # Returns
89    ///
90    /// An `MLDSASignature` if the bytes represent a valid signature for the given level,
91    /// or an error otherwise.
92    ///
93    /// # Errors
94    ///
95    /// Returns an error if the bytes do not represent a valid ML-DSA signature
96    /// for the specified security level.
97    pub fn from_bytes(level: MLDSA, bytes: &[u8]) -> Result<Self> {
98        match level {
99            MLDSA::MLDSA44 => Ok(MLDSASignature::MLDSA44(Box::new(
100                mldsa44::DetachedSignature::from_bytes(bytes).map_err(|e| anyhow!(e))?,
101            ))),
102            MLDSA::MLDSA65 => Ok(MLDSASignature::MLDSA65(Box::new(
103                mldsa65::DetachedSignature::from_bytes(bytes).map_err(|e| anyhow!(e))?,
104            ))),
105            MLDSA::MLDSA87 => Ok(MLDSASignature::MLDSA87(Box::new(
106                mldsa87::DetachedSignature::from_bytes(bytes).map_err(|e| anyhow!(e))?,
107            ))),
108        }
109    }
110}
111
112/// Provides debug formatting for ML-DSA signatures.
113impl std::fmt::Debug for MLDSASignature {
114    /// Formats the signature as a string for debugging purposes.
115    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
116        match self {
117            MLDSASignature::MLDSA44(_) => f.write_str("MLDSA44Signature"),
118            MLDSASignature::MLDSA65(_) => f.write_str("MLDSA65Signature"),
119            MLDSASignature::MLDSA87(_) => f.write_str("MLDSA87Signature"),
120        }
121    }
122}
123
124/// Defines CBOR tags for ML-DSA signatures.
125impl CBORTagged for MLDSASignature {
126    /// Returns the CBOR tag for ML-DSA signatures.
127    fn cbor_tags() -> Vec<Tag> {
128        tags_for_values(&[tags::TAG_MLDSA_SIGNATURE])
129    }
130}
131
132/// Converts an `MLDSASignature` to CBOR.
133impl From<MLDSASignature> for CBOR {
134    /// Converts to tagged CBOR.
135    fn from(value: MLDSASignature) -> Self {
136        value.tagged_cbor()
137    }
138}
139
140/// Implements CBOR encoding for ML-DSA signatures.
141impl CBORTaggedEncodable for MLDSASignature {
142    /// Creates the untagged CBOR representation as an array with level and signature bytes.
143    fn untagged_cbor(&self) -> CBOR {
144        vec![self.level().into(), CBOR::to_byte_string(self.as_bytes())].into()
145    }
146}
147
148/// Attempts to convert CBOR to an `MLDSASignature`.
149impl TryFrom<CBOR> for MLDSASignature {
150    type Error = Error;
151
152    /// Converts from tagged CBOR.
153    fn try_from(cbor: CBOR) -> Result<Self, Self::Error> {
154        Self::from_tagged_cbor(cbor)
155    }
156}
157
158/// Implements CBOR decoding for ML-DSA signatures.
159impl CBORTaggedDecodable for MLDSASignature {
160    /// Creates an `MLDSASignature` from untagged CBOR.
161    ///
162    /// # Errors
163    /// Returns an error if the CBOR value doesn't represent a valid ML-DSA signature.
164    fn from_untagged_cbor(untagged_cbor: CBOR) -> Result<Self> {
165        match untagged_cbor.as_case() {
166            CBORCase::Array(elements) => {
167                if elements.len() != 2 {
168                    bail!("MLDSASignature must have two elements");
169                }
170
171                let level = MLDSA::try_from(elements[0].clone())?;
172                let data = CBOR::try_into_byte_string(elements[1].clone())?;
173                MLDSASignature::from_bytes(level, &data)
174            }
175            _ => bail!("MLDSASignature must be an array"),
176        }
177    }
178}
bc_components/mldsa/mldsa_signature.rs

bc_components/mldsa/
mldsa_signature.rs
