1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
//! # Digital Signatures
//!
//! This module provides a unified interface for both post-quantum and classical
//! digital signature schemes. It supports the following algorithms:
//!
//! ## Post-Quantum Algorithms
//!
//! ### ML-DSA (FIPS 204)
//! Module-Lattice-Based Digital Signature Algorithm providing EUF-CMA security.
//!
//! - **ML-DSA-44**: NIST Security Category 2 (~128-bit classical security)
//! - Public key: 1312 bytes
//! - Secret key: 2560 bytes
//! - Signature: ~2.4 KB
//!
//! - **ML-DSA-65**: NIST Security Category 3 (~192-bit classical security)
//! - Public key: 1952 bytes
//! - Secret key: 4032 bytes
//! - Signature: ~3.3 KB
//!
//! - **ML-DSA-87**: NIST Security Category 5 (~256-bit classical security)
//! - Public key: 2592 bytes
//! - Secret key: 4896 bytes
//! - Signature: ~4.6 KB
//!
//! ### SLH-DSA (FIPS 205)
//! Stateless Hash-Based Digital Signature Algorithm providing EUF-CMA security
//! with conservative security guarantees.
//!
//! - **SLH-DSA-SHAKE-128s**: NIST Security Category 1
//! - Very long keys, but quantum-resistant
//! - Stateless: No secret state that needs updating
//! - Signatures can be made as many times as needed
//!
//! - **SLH-DSA-SHAKE-192s**: NIST Security Category 3
//! - Balanced security and performance
//!
//! - **SLH-DSA-SHAKE-256s**: NIST Security Category 5
//! - Highest security level
//!
//! ### FN-DSA (draft FIPS 206 / Falcon)
//! Fast-Fourier Lattice-based signature scheme based on NTRU lattices. NIST
//! selected Falcon for standardization as FIPS 206, but **the final standard
//! has not been published yet** (Falcon remains in the standardization
//! pipeline as of this writing).
//! "FN" stands for "Falcon-NTRU"; despite the name, FN-DSA is a *many-time*
//! signature scheme — there is no upper bound on the number of signatures
//! producible per key (prior revisions of this doc incorrectly called it
//! "Few-Time"). Provides compact signatures with lattice-based security.
//!
//! - **FN-DSA-512**: NIST Category 1 (~103-bit quantum, ~128-bit classical)
//! - Public key: 897 bytes
//! - Secret key: 1281 bytes
//! - Signature: ~666 bytes average (variable-length encoding)
//!
//! - **FN-DSA-1024**: NIST Category 5 (~230-bit quantum, ~256-bit classical)
//! - Public key: 1793 bytes
//! - Secret key: 2305 bytes
//! - Signature: ~1280 bytes average
//!
//! ## Classical Algorithms
//!
//! This crate only exposes **Ed25519** (EdDSA over Curve25519) as a classical
//! signature primitive. It is used in the hybrid ML-DSA-65 + Ed25519
//! construction in [`hybrid::sig_hybrid`](crate::hybrid::sig_hybrid) and as a
//! standalone signer via [`primitives::ec::ed25519`](crate::primitives::ec::ed25519).
//! **ECDSA over NIST P-curves (P-256/P-384/P-521) is NOT implemented** —
//! prior revisions of this doc listed them, which was aspirational. For
//! secp256k1 blockchain / interoperability use cases, see
//! `crate::primitives::ec::secp256k1` (available with the default feature set;
//! gated out under `--features fips`).
//!
//! ## Security Properties
//!
//! All signature implementations in this module provide:
//!
//! - **EUF-CMA**: Existential Unforgeability under Chosen Message Attacks
//! - An adversary cannot forge a valid signature even when given
//! signatures on arbitrary messages of their choice
//!
//! - **Constant-time**: All secret-handling operations execute in constant time
//! - Protects against timing side-channel attacks
//!
//! - **Zeroization**: Secret keys are securely wiped when dropped
//! - Prevents secret material from remaining in memory
//!
//! - **Domain Separation**: Optional context string parameter
//! - Prevents signature reuse across different applications
//!
//! ## Algorithm Comparison
//!
//! | Algorithm | Key Size | Signature Size | Security | Best For |
//! |-----------|-----------|----------------|----------|----------|
//! | ML-DSA-44 | ~2.4 KB | ~2.4 KB | 128-bit | Balanced security/performance |
//! | ML-DSA-65 | ~3.6 KB | ~3.3 KB | 192-bit | High-security applications |
//! | ML-DSA-87 | ~4.6 KB | ~4.6 KB | 256-bit | Maximum security |
//! | SLH-DSA-SHAKE | Large | ~41 KB | Conservative | Long-term security, stateless |
//! | FN-DSA-512 | ~1.3 KB | 666 bytes | 128-bit | Compact signatures, fast verify |
//! | FN-DSA-1024 | ~2.3 KB | 1280 bytes | 256-bit | High-security with compact sigs |
//!
//! ## Example Usage
//!
//! ### ML-DSA Signing and Verification
//!
//! ```no_run
//! use latticearc::primitives::sig::ml_dsa::{MlDsaParameterSet, generate_keypair};
//!
//! // Generate keypair
//! let (pk, sk) = generate_keypair(MlDsaParameterSet::MlDsa65)?;
//!
//! // Sign a message (empty context = no domain separation)
//! let message = b"Hello, post-quantum world!";
//! let signature = sk.sign(message, &[])?;
//!
//! // Verify signature
//! let is_valid = pk.verify(message, &signature, &[])?;
//! assert!(is_valid);
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! ### SLH-DSA with Context
//!
//! ```no_run
//! use latticearc::primitives::sig::slh_dsa::{SlhDsaSecurityLevel, SigningKey, VerifyingKey};
//!
//! let (sk, pk) = SigningKey::generate(SlhDsaSecurityLevel::Shake128s)?;
//!
//! let message = b"Important document";
//! let context = b"my-application-v1"; // Domain separation
//!
//! let signature = sk.sign(message, context)?;
//! let is_valid = pk.verify(message, &signature, context)?;
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! ## FIPS Compliance
//!
//! All post-quantum signature algorithms are fully compliant with their respective FIPS standards:
//!
//! - **ML-DSA**: [FIPS 204](https://csrc.nist.gov/pubs/fips/204/final/)
//! - **SLH-DSA**: [FIPS 205](https://csrc.nist.gov/pubs/fips/205/final/)
//! - **FN-DSA**: [FIPS 206 (pending, Falcon selected for standardization)](https://csrc.nist.gov/Projects/post-quantum-cryptography)
//!
//! All implementations use audited FIPS-standard crates (fips204, fips205, fn-dsa).
//!
//! ## Mathematical Correctness
//!
//! ### ML-DSA
//! Based on Module-SIS (Short Integer Solution) lattice problem.
//! The security reduction proves that forging a signature requires solving
//! the Module-SIS problem, which is believed to be hard for quantum computers.
//!
//! ### SLH-DSA
//! Based on Merkle tree hash-based signatures. Security relies on
//! collision resistance of the underlying hash function (SHAKE).
//! Provides information-theoretic security against quantum attacks.
//!
//! ### FN-DSA
//! Based on the NTRU lattice problem (Shortest Vector Problem).
//! Provides provable security with compact signatures.
//!
//! ## Security Considerations
//!
//! - **Key Generation**: Always use cryptographically secure random number generators
//! - **Key Storage**: Store secret keys securely, never transmit them
//! - **Signature Reuse**: SLH-DSA is stateless (no signature reuse concerns)
//! - **Context Parameter**: Use non-empty context strings for domain separation
//! - **Algorithm Selection**: Choose algorithm based on your security requirements
//! and performance constraints
//!
//! ## Module Structure
//!
//! - [`ml_dsa`]: ML-DSA (FIPS 204) lattice-based signatures
//! - [`slh_dsa`]: SLH-DSA (FIPS 205) hash-based signatures
//! - [`fndsa`]: FN-DSA (FIPS 206) compact lattice signatures
// Each algorithm submodule owns the canonical path for its types. We do NOT
// glob-re-export their contents here because `SigningKey` / `VerifyingKey`
// collide across fndsa, ml_dsa, and slh_dsa. Downstream consumers should
// import the specific algorithm they want:
// use latticearc::primitives::sig::fndsa::{SigningKey, VerifyingKey};
//
// Parameter-set and security-level enums are re-exported from
// `crate::primitives` with algorithm-prefixed names (`FnDsaSecurityLevel`,
// `SlhDsaSecurityLevel`, `MlDsaParameterSet`).