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: - ```` (uses ``SM3``) - ``,`` -#. Dilithium. +#. ML-DSA (Dilithium). Takes the optional parameter ``Deterministic`` (default) or ``Randomized``. #. SPHINCS+. Takes the optional parameter ``Deterministic`` (default) or ``Randomized``. diff --git a/doc/api_ref/python.rst b/doc/api_ref/python.rst index 9575587f53..e605eeea7b 100644 --- a/doc/api_ref/python.rst +++ b/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 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 { *
Key Encapsulation Mechanisms
* @ref frodokem.h "FrodoKEM", @ref kyber.h "Kyber", @ref rsa.h "RSA" *
Public Key Signature Schemes
-* @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" *
Key Agreement