crypto/mldsa/mod.rs
1//! ML-DSA post-quantum signatures standardized in FIPS 204.
2//!
3//! This module implements the ML-DSA-44, ML-DSA-65 and ML-DSA-87 parameter
4//! sets through distinct key types:
5//!
6//! | Parameter set | Secret key | Public key | Public key size | Signature size |
7//! | --- | --- | --- | --- | --- |
8//! | ML-DSA-44 | [`MlDsa44SecretKey`] | [`MlDsa44PublicKey`] | 1312 B | 2420 B |
9//! | ML-DSA-65 | [`MlDsa65SecretKey`] | [`MlDsa65PublicKey`] | 1952 B | 3309 B |
10//! | ML-DSA-87 | [`MlDsa87SecretKey`] | [`MlDsa87PublicKey`] | 2592 B | 4627 B |
11//!
12//! # Signing
13//!
14//! Signing is stateful: build a secret key from a 32-byte seed with `new` (or
15//! with `generate` for a fresh random key), then call `sign` (randomized) or
16//! `sign_derand` (deterministic for a fixed nonce).
17//!
18//! The expanded key caches the NTT-domain matrix and secret vectors, so
19//! repeated signatures skip key generation. It is a fixed-size value with no
20//! heap allocation:
21//!
22//! ```
23//! # use crypto::mldsa::MlDsa65SecretKey;
24//! # let seed = [0u8; 32];
25//! let key = MlDsa65SecretKey::new(&seed);
26//! let signature = key.sign_derand(b"message", b"", &[0u8; 32]).unwrap();
27//! assert!(key.public_key().verify(b"message", &signature, b"").is_ok());
28//! ```
29//!
30//! # Verification
31//!
32//! Verification is stateless: the public key returned by the secret key's
33//! `public_key` method (or built from raw bytes with `from_bytes`)
34//! exposes `verify` for a message and optional context, and
35//! `verify_external_mu` for a precomputed 64-byte message representative
36//! (FIPS 204 "external μ"). Both return [`MlDsaError`] on failure.
37
38mod mldsa;
39mod mldsa44;
40mod mldsa65;
41mod mldsa87;
42
43pub use mldsa::MlDsaError;
44pub use mldsa44::{
45 ML_DSA_44_CONTEXT_MAX_LEN, ML_DSA_44_PUBLIC_KEY_SIZE, ML_DSA_44_SECRET_KEY_SIZE, ML_DSA_44_SEED_SIZE,
46 ML_DSA_44_SIGNATURE_SIZE, MlDsa44PublicKey, MlDsa44SecretKey,
47};
48pub use mldsa65::{
49 ML_DSA_65_CONTEXT_MAX_LEN, ML_DSA_65_PUBLIC_KEY_SIZE, ML_DSA_65_SECRET_KEY_SIZE, ML_DSA_65_SEED_SIZE,
50 ML_DSA_65_SIGNATURE_SIZE, MlDsa65PublicKey, MlDsa65SecretKey,
51};
52pub use mldsa87::{
53 ML_DSA_87_CONTEXT_MAX_LEN, ML_DSA_87_PUBLIC_KEY_SIZE, ML_DSA_87_SECRET_KEY_SIZE, ML_DSA_87_SEED_SIZE,
54 ML_DSA_87_SIGNATURE_SIZE, MlDsa87PublicKey, MlDsa87SecretKey,
55};
56
57#[cfg(test)]
58mod tests;