bc_components/mldsa/
mldsa_private_key.rs

1use dcbor::prelude::*;
2use pqcrypto_mldsa::*;
3use pqcrypto_traits::sign::*;
4
5use super::{MLDSA, MLDSASignature};
6use crate::{Digest, Error, Reference, ReferenceProvider, Result, tags};
7
8/// A private key for the ML-DSA post-quantum digital signature algorithm.
9///
10/// `MLDSAPrivateKey` represents a private key that can be used to create
11/// digital signatures using the ML-DSA (Module Lattice-based Digital Signature
12/// Algorithm) post-quantum algorithm. It supports multiple security levels
13/// 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/// # Security
20///
21/// ML-DSA private keys should be kept secure and never exposed. They provide
22/// resistance against attacks from both classical and quantum computers.
23///
24/// # Examples
25///
26/// ```
27/// use bc_components::MLDSA;
28///
29/// // Generate a keypair
30/// let (private_key, public_key) = MLDSA::MLDSA44.keypair();
31///
32/// // Sign a message
33/// let message = b"Hello, post-quantum world!";
34/// let signature = private_key.sign(message);
35/// ```
36#[derive(Clone, PartialEq)]
37pub enum MLDSAPrivateKey {
38    /// An ML-DSA44 private key (NIST security level 2)
39    MLDSA44(Box<mldsa44::SecretKey>),
40    /// An ML-DSA65 private key (NIST security level 3)
41    MLDSA65(Box<mldsa65::SecretKey>),
42    /// An ML-DSA87 private key (NIST security level 5)
43    MLDSA87(Box<mldsa87::SecretKey>),
44}
45
46impl MLDSAPrivateKey {
47    /// Signs a message using this ML-DSA private key.
48    ///
49    /// # Parameters
50    ///
51    /// * `message` - The message to sign.
52    ///
53    /// # Returns
54    ///
55    /// An `MLDSASignature` for the message, using the same security level as
56    /// this private key.
57    ///
58    /// # Examples
59    ///
60    /// ```
61    /// use bc_components::MLDSA;
62    ///
63    /// let (private_key, _) = MLDSA::MLDSA44.keypair();
64    /// let message = b"Hello, world!";
65    /// let signature = private_key.sign(message);
66    /// ```
67    pub fn sign(&self, message: impl AsRef<[u8]>) -> MLDSASignature {
68        match self {
69            MLDSAPrivateKey::MLDSA44(sk) => MLDSASignature::MLDSA44(Box::new(
70                mldsa44::detached_sign(message.as_ref(), sk),
71            )),
72            MLDSAPrivateKey::MLDSA65(sk) => MLDSASignature::MLDSA65(Box::new(
73                mldsa65::detached_sign(message.as_ref(), sk),
74            )),
75            MLDSAPrivateKey::MLDSA87(sk) => MLDSASignature::MLDSA87(Box::new(
76                mldsa87::detached_sign(message.as_ref(), sk),
77            )),
78        }
79    }
80
81    /// Returns the security level of this ML-DSA private key.
82    pub fn level(&self) -> MLDSA {
83        match self {
84            MLDSAPrivateKey::MLDSA44(_) => MLDSA::MLDSA44,
85            MLDSAPrivateKey::MLDSA65(_) => MLDSA::MLDSA65,
86            MLDSAPrivateKey::MLDSA87(_) => MLDSA::MLDSA87,
87        }
88    }
89
90    /// Returns the size of this ML-DSA private key in bytes.
91    pub fn size(&self) -> usize { self.level().private_key_size() }
92
93    /// Returns the raw bytes of this ML-DSA private key.
94    pub fn as_bytes(&self) -> &[u8] { self.as_ref() }
95
96    /// Creates an ML-DSA private key from raw bytes and a security level.
97    ///
98    /// # Parameters
99    ///
100    /// * `level` - The security level of the key.
101    /// * `bytes` - The raw bytes of the key.
102    ///
103    /// # Returns
104    ///
105    /// An `MLDSAPrivateKey` if the bytes represent a valid key for the given
106    /// level, or an error otherwise.
107    ///
108    /// # Errors
109    ///
110    /// Returns an error if the bytes do not represent a valid ML-DSA private
111    /// key for the specified security level.
112    pub fn from_bytes(level: MLDSA, bytes: &[u8]) -> Result<Self> {
113        match level {
114            MLDSA::MLDSA44 => Ok(MLDSAPrivateKey::MLDSA44(Box::new(
115                mldsa44::SecretKey::from_bytes(bytes)
116                    .map_err(|e| Error::post_quantum(e.to_string()))?,
117            ))),
118            MLDSA::MLDSA65 => Ok(MLDSAPrivateKey::MLDSA65(Box::new(
119                mldsa65::SecretKey::from_bytes(bytes)
120                    .map_err(|e| Error::post_quantum(e.to_string()))?,
121            ))),
122            MLDSA::MLDSA87 => Ok(MLDSAPrivateKey::MLDSA87(Box::new(
123                mldsa87::SecretKey::from_bytes(bytes)
124                    .map_err(|e| Error::post_quantum(e.to_string()))?,
125            ))),
126        }
127    }
128}
129
130impl AsRef<[u8]> for MLDSAPrivateKey {
131    /// Returns the private key as a byte slice.
132    fn as_ref(&self) -> &[u8] {
133        match self {
134            MLDSAPrivateKey::MLDSA44(key) => key.as_bytes(),
135            MLDSAPrivateKey::MLDSA65(key) => key.as_bytes(),
136            MLDSAPrivateKey::MLDSA87(key) => key.as_bytes(),
137        }
138    }
139}
140
141/// Provides debug formatting for ML-DSA private keys.
142impl std::fmt::Debug for MLDSAPrivateKey {
143    /// Formats the private key as a string for debugging purposes.
144    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
145        match self {
146            MLDSAPrivateKey::MLDSA44(_) => f.write_str("MLDSA44PrivateKey"),
147            MLDSAPrivateKey::MLDSA65(_) => f.write_str("MLDSA65PrivateKey"),
148            MLDSAPrivateKey::MLDSA87(_) => f.write_str("MLDSA87PrivateKey"),
149        }
150    }
151}
152
153/// Defines CBOR tags for ML-DSA private keys.
154impl CBORTagged for MLDSAPrivateKey {
155    /// Returns the CBOR tag for ML-DSA private keys.
156    fn cbor_tags() -> Vec<Tag> {
157        tags_for_values(&[tags::TAG_MLDSA_PRIVATE_KEY])
158    }
159}
160
161/// Converts an `MLDSAPrivateKey` to CBOR.
162impl From<MLDSAPrivateKey> for CBOR {
163    /// Converts to tagged CBOR.
164    fn from(value: MLDSAPrivateKey) -> Self { value.tagged_cbor() }
165}
166
167/// Implements CBOR encoding for ML-DSA private keys.
168impl CBORTaggedEncodable for MLDSAPrivateKey {
169    /// Creates the untagged CBOR representation as an array with level and key
170    /// bytes.
171    fn untagged_cbor(&self) -> CBOR {
172        vec![self.level().into(), CBOR::to_byte_string(self.as_bytes())].into()
173    }
174}
175
176/// Attempts to convert CBOR to an `MLDSAPrivateKey`.
177impl TryFrom<CBOR> for MLDSAPrivateKey {
178    type Error = dcbor::Error;
179
180    /// Converts from tagged CBOR.
181    fn try_from(cbor: CBOR) -> dcbor::Result<Self> {
182        Self::from_tagged_cbor(cbor)
183    }
184}
185
186/// Implements CBOR decoding for ML-DSA private keys.
187impl CBORTaggedDecodable for MLDSAPrivateKey {
188    /// Creates an `MLDSAPrivateKey` from untagged CBOR.
189    ///
190    /// # Errors
191    /// Returns an error if the CBOR value doesn't represent a valid ML-DSA
192    /// private key.
193    fn from_untagged_cbor(untagged_cbor: CBOR) -> dcbor::Result<Self> {
194        match untagged_cbor.as_case() {
195            CBORCase::Array(elements) => {
196                if elements.len() != 2 {
197                    return Err("MLDSAPrivateKey must have two elements".into());
198                }
199
200                let level = MLDSA::try_from(elements[0].clone())?;
201                let data = CBOR::try_into_byte_string(elements[1].clone())?;
202                Ok(MLDSAPrivateKey::from_bytes(level, &data)?)
203            }
204            _ => Err("MLDSAPrivateKey must be an array".into()),
205        }
206    }
207}
208
209impl ReferenceProvider for MLDSAPrivateKey {
210    fn reference(&self) -> Reference {
211        Reference::from_digest(Digest::from_image(
212            self.tagged_cbor().to_cbor_data(),
213        ))
214    }
215}
216
217impl std::fmt::Display for MLDSAPrivateKey {
218    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
219        match self {
220            MLDSAPrivateKey::MLDSA44(_) => {
221                write!(f, "MLDSA44PrivateKey({})", self.ref_hex_short())
222            }
223            MLDSAPrivateKey::MLDSA65(_) => {
224                write!(f, "MLDSA65PrivateKey({})", self.ref_hex_short())
225            }
226            MLDSAPrivateKey::MLDSA87(_) => {
227                write!(f, "MLDSA87PrivateKey({})", self.ref_hex_short())
228            }
229        }
230    }
231}
bc_components/mldsa/mldsa_private_key.rs

bc_components/mldsa/
mldsa_private_key.rs
