bc_components/mldsa/
mldsa_signature.rs

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

bc_components/mldsa/
mldsa_signature.rs
