From 02b905891962d4e8f7ebe9caedfcd503924caf32 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ren=C3=A9=20Meusel?= <rene.meusel@rohde-schwarz.com>
Date: Fri, 20 Sep 2024 17:01:59 +0200
Subject: [PATCH] ML-DSA: update documentation

---
 doc/api_ref/pubkey.rst | 28 +++++++++++++++++++++++-----
 readme.rst             |  2 +-
 src/lib/utils/types.h  |  2 +-
 3 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/doc/api_ref/pubkey.rst b/doc/api_ref/pubkey.rst
index d327accafe..c19e5af4e0 100644
--- a/doc/api_ref/pubkey.rst
+++ b/doc/api_ref/pubkey.rst
@@ -21,7 +21,7 @@ removed in a future major release.
   .. cpp:function:: std::string algo_name()
 
      Return a short string identifying the algorithm of this key,
-     eg "RSA" or "Dilithium".
+     eg "RSA" or "ML-DSA".
 
   .. cpp:function:: size_t estimated_strength() const
 
@@ -110,10 +110,28 @@ ECDH, DH, X25519 and X448
 Key agreement schemes. DH uses arithmetic over finite fields and is slower and
 with larger keys. ECDH, X25519 and X448 use elliptic curves instead.
 
-Dilithium
-~~~~~~~~~~
+ML-DSA (FIPS 204)
+~~~~~~~~~~~~~~~~~
+
+Post-quantum secure signature scheme based on (structured) lattices.
+This algorithm is standardized in FIPS 204. Signing keys are always stored and
+expanded from the 32-byte private random seed (`xi`), loading the expanded key
+format specified in FIPS 204 is explicitly not supported.
+
+Support for ML-DSA is implemented in the module ``ml_dsa``
+
+Additionally, support for the pre-standardized version "Dilithium" is retained
+for the time being. The implemented specification is commonly referred to as
+version 3.1 of the CRYSTALS-Dilithium submission to NIST's third round of the
+PQC competition. This is not compatible to the "Initial Public Draft" version of
+FIPS 204 for which Botan does not offer an implementation.
+
+Currently two flavors of Dilithium are implemented in separate Botan modules:
 
-Post-quantum secure signature scheme based on lattice problems.
+ * ``dilithium``, that uses Keccak (SHAKE), and that saw some public usage
+   by early adopters.
+ * ``dilithium_aes``, that uses AES instead of Keccak-based primitives.
+   This mode is deprecated and will be removed in a future release.
 
 Kyber
 ~~~~~~~~~~~
@@ -807,7 +825,7 @@ Botan implements the following signature algorithms:
    - ``<user ID>`` (uses ``SM3``)
    - ``<user ID>,<HashFunction>``
 
-#. Dilithium.
+#. ML-DSA (Dilithium).
    Takes the optional parameter ``Deterministic`` (default) or ``Randomized``.
 #. SPHINCS+.
    Takes the optional parameter ``Deterministic`` (default) or ``Randomized``.
diff --git a/readme.rst b/readme.rst
index 78a8422946..86f8f926fe 100644
--- a/readme.rst
+++ b/readme.rst
@@ -102,7 +102,7 @@ Public Key Cryptography
 * RSA signatures and encryption
 * DH and ECDH key agreement
 * Signature schemes ECDSA, DSA, Ed25519, Ed448, ECGDSA, ECKCDSA, SM2, GOST 34.10
-* Post-quantum signature schemes Dilithium, HSS/LMS, SPHINCS+, XMSS
+* Post-quantum signature schemes ML-DSA (Dilithium), HSS/LMS, SPHINCS+, XMSS
 * Post-quantum key agreement schemes McEliece, Kyber, and FrodoKEM
 * ElGamal encryption
 * Padding schemes OAEP, PSS, PKCS #1 v1.5, X9.31
diff --git a/src/lib/utils/types.h b/src/lib/utils/types.h
index aa2f91a19c..6f904c2702 100644
--- a/src/lib/utils/types.h
+++ b/src/lib/utils/types.h
@@ -59,7 +59,7 @@ namespace Botan {
 * <dt>Key Encapsulation Mechanisms<dd>
 *        @ref frodokem.h "FrodoKEM", @ref kyber.h "Kyber", @ref rsa.h "RSA"
 * <dt>Public Key Signature Schemes<dd>
-*        @ref dsa.h "DSA", @ref dilithium.h "Dilithium", @ref ecdsa.h "ECDSA", @ref ecgdsa.h "ECGDSA",
+*        @ref dsa.h "DSA", @ref dilithium.h "ML-DSA/Dilithium", @ref ecdsa.h "ECDSA", @ref ecgdsa.h "ECGDSA",
 *        @ref eckcdsa.h "ECKCDSA", @ref gost_3410.h "GOST 34.10-2001", @ref hss_lms.h "HSS/LMS", @ref sm2.h "SM2",
          @ref sphincsplus.h "SPHINCS+", @ref xmss.h "XMSS"
 * <dt>Key Agreement<dd>