WIP

docs/cryptodoc/src/05_00_pubkey.rst

@@ -21,5 +21,6 @@ encapsulation and decapsulation or the key exchange mechanism.
    05_06_hss_lms
    05_07_spx
    05_08_dilithium
+   05_08_ml_dsa
    05_09_kyber
    05_10_frodokem

docs/cryptodoc/src/05_08_ml_dsa.rst

@@ -0,0 +1,107 @@
+.. _pubkey/ml_dsa:
+
+ML-DSA
+======
+
+Botan implements the Module-Lattice-based Digital Signature Algorithm (ML-DSA)
+in :srcref:`src/lib/pubkey/dilithium`. The implementation is based on
+[FIPS-204]_. The list of supported algorithm parametres is listed in the table
+:ref:`pubkey/ml_dsa/params`.
+
+.. _pubkey/ml_dsa/params:
+
+.. table:: Supported ML-DSA Parameter Sets (see Table 1 of [FIPS-204]_)
+
+   +------------+-----------+-----------+---------------+-----------+--------------+-----------------+------------------+------------------+---------------+--------------+---------------+----------------+
+   | Mode       | :math:`q` | :math:`n` | :math:`\zeta` | :math:`d` | :math:`\tau` | :math:`\lambda` | :math:`\gamma_1` | :math:`\gamma_2` | :math:`(k,l)` | :math:`\eta` | :math:`\beta` | :math:`\omega` |
+   +============+===========+===========+===============+===========+==============+=================+==================+==================+===============+==============+===============+================+
+   | ML-DSA-4x4 | 8380417   | 256       | 1753          | 13        | 39           | 128             | 2\ :sup:`17`     | :math:`(q-1)/88` | (4,4)         | 2            | 78            | 80             |
+   +------------+-----------+-----------+---------------+-----------+--------------+-----------------+------------------+------------------+---------------+--------------+---------------+----------------+
+   | ML-DSA-6x5 | 8380417   | 256       | 1753          | 13        | 49           | 192             | 2\ :sup:`19`     | :math:`(q-1)/32` | (6,5)         | 4            | 196           | 55             |
+   +------------+-----------+-----------+---------------+-----------+--------------+-----------------+------------------+------------------+---------------+--------------+---------------+----------------+
+   | ML-DSA-8x7 | 8380417   | 256       | 1753          | 13        | 60           | 256             | 2\ :sup:`19`     | :math:`(q-1)/32` | (8,7)         | 2            | 120           | 75             |
+   +------------+-----------+-----------+---------------+-----------+--------------+-----------------+------------------+------------------+---------------+--------------+---------------+----------------+
+
+The parameter sets claim a NIST security level of 2, 3, and 5 respectively.
+
+.. _pubkey/ml_dsa/internals:
+
+Algorithm Internals
+-------------------
+
+[FIPS-204]_ describes three primary operations: key generation, signing, and
+verification.
+
+Internally, those operations are further split into two functional layers:
+the public-facing ML-DSA (Section 5), and ML-DSA-internal (Section 6). ML-DSA
+and ML-DSA-internal decouple the actual high-level logic from the generation of
+randomness. The functions in ML-DSA-internal receive pre-determined random bytes
+as needed and are, therefore, fully deterministic.
+
+ML-DSA is a Schnorr-like signature where the typically interactive protocol is
+made non-interactive by pseudorandomly deriving the verifier's challenge from
+the commitment and the message to be signed.
+
+.. _pubkey/ml_dsa/components:
+
+.. table:: ML-DSA Components and File Locations
+
+   +----------------------------------------------------------+----------------------------------------------------------------------------------------+----------------------------------------------------------------+--------------------------+
+   | Component                                                | Source Location                                                                        | Purpose                                                        | Section in [FIPS-204]_   |
+   +==========================================================+========================================================================================+================================================================+==========================+
+   | :ref:`Types <pubkey/ml_dsa/types>`                       | :srcref:`[src/lib/pubkey/dilithium/dilithium_common]/dilithium_types.h`                | Strong Types                                                   | TBD                      |
+   +----------------------------------------------------------+----------------------------------------------------------------------------------------+----------------------------------------------------------------+--------------------------+
+   | :ref:`Constants <pubkey/ml_dsa/constants>`               | :srcref:`[src/lib/pubkey/dilithium/dilithium_common]/dilithium_constants.h`            | Parameter set instantiation                                    | TBD                      |
+   +----------------------------------------------------------+----------------------------------------------------------------------------------------+----------------------------------------------------------------+--------------------------+
+   | :ref:`Polynomials <pubkey/ml_dsa/polynomials>`           | :srcref:`[src/lib/pubkey/dilithium/dilithium_common]/dilithium_polynomial.h`           | Polynomials, Structures on Polynomials and Operations          | TBD                      |
+   +----------------------------------------------------------+----------------------------------------------------------------------------------------+----------------------------------------------------------------+--------------------------+
+   | :ref:`Algorithms <pubkey/ml_dsa/algorithms>`             | :srcref:`[src/lib/pubkey/dilithium/dilithium_common]/dilithium_algos.h`                | Encoding, Sampling, Key Expansion, Hint Generation, Rounding   | TBD                      |
+   +----------------------------------------------------------+----------------------------------------------------------------------------------------+----------------------------------------------------------------+--------------------------+
+   | :ref:`Symmetric Primitives <pubkey/ml_dsa/primitives>`   | :srcref:`[src/lib/pubkey/dilithium/dilithium_common]/dilithium_symmetric_primitives.h` | ML-DSA abstractions for PRFs, XOFs, Hashes, and KDFs           | TBD                      |
+   +----------------------------------------------------------+----------------------------------------------------------------------------------------+----------------------------------------------------------------+--------------------------+
+   | :ref:`Internal Keys <pubkey/ml_dsa/keys>`                | :srcref:`[src/lib/pubkey/dilithium/dilithium_common]/dilithium_keys.h`                 | Internal key representation and serialization                  | TBD                      |
+   +----------------------------------------------------------+----------------------------------------------------------------------------------------+----------------------------------------------------------------+--------------------------+
+   | :ref:`ML-DSA Implementation <pubkey/ml_dsa/ml_dsa_impl>` | :srcref:`[src/lib/pubkey/dilithium/ml_dsa]/ml_dsa_impl.h`                              | Functional disambiguation to (also provided) Dilithium         | TBD                      |
+   +----------------------------------------------------------+----------------------------------------------------------------------------------------+----------------------------------------------------------------+--------------------------+
+   | :ref:`ML-DSA <pubkey/ml_dsa/ml_dsa_api>`                 | :srcref:`[src/lib/pubkey/dilithium/dilithium_common]/dilithium.h`                      | Public ML-DSA API                                              | TBD                      |
+   +----------------------------------------------------------+----------------------------------------------------------------------------------------+----------------------------------------------------------------+--------------------------+
+
+.. _pubkey/ml_dsa/types:
+
+Strong Types
+^^^^^^^^^^^^
+
+.. _pubkey/ml_dsa/constants:
+
+Paramter Instantiations
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _pubkey/ml_dsa/polynomials:
+
+Polynomial Operations
+^^^^^^^^^^^^^^^^^^^^^
+
+.. _pubkey/ml_dsa/algorithms:
+
+Internal Algorithms
+^^^^^^^^^^^^^^^^^^^
+
+.. _pubkey/ml_dsa/primitives:
+
+Symmetric Primitives
+^^^^^^^^^^^^^^^^^^^^
+
+.. _pubkey/ml_dsa/keys:
+
+Internal Key Representation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _pubkey/ml_dsa/ml_dsa_impl:
+
+ML-DSA Specifics
+^^^^^^^^^^^^^^^^
+
+.. _pubkey/ml_dsa/ml_dsa_api:
+
+Public API
+^^^^^^^^^^

docs/cryptodoc/src/90_bibliographie.rst

@@ -51,6 +51,10 @@
    SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions.
    http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf
 
+.. [FIPS-204] Federal Information Processing Standards Publication 204.
+   Module-Lattice-Based Digital Signature Standard.
+   http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.204.pdf
+
 .. [FrodoKEM-ISO] Erdem Alkim, Joppe W. Bos, Léo Ducas, Patrick Longa, Ilya Mironov, Michael Naehrig, Valeria Nikolaenko, Chris Peikert, Ananth Raghunathan, Douglas Stebila
    "FrodoKEM: Learning With Errors Key Encapsulation Preliminary Standardization Proposal (2023-03-14)",
    Preliminary Standardization Proposal submitted to ISO, 2023,