ML-DSA: update documentation

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``.

doc/api_ref/python.rst

@@ -299,6 +299,11 @@ Public Key
      "sm2p256v1") and the public point as a pair of integers giving
      the affine coordinates.
 
+  .. py:classmethod:: load_ml_dsa(mode, raw_encoding)
+
+     Load an ML-DSA public key giving the mode as a string (like
+     "ML-DSA-4x4") and the raw encoding of the public key.
+
   .. py:method:: check_key(rng_obj, strong=True):
 
      Test the key for consistency. If ``strong`` is ``True`` then
@@ -390,6 +395,10 @@ Private Key
 
      Return a private SM2 key
 
+   .. py:classmethod:: load_ml_dsa(mode, raw_encoding)
+
+      Return a private ML-DSA key
+
   .. py:method:: get_public_key()
 
      Return a public_key object

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

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>