ML-KEM: update documentation

doc/api_ref/pubkey.rst

@@ -115,19 +115,28 @@ Dilithium
 
 Post-quantum secure signature scheme based on lattice problems.
 
-Kyber
-~~~~~~~~~~~
+ML-KEM (FIPS 203)
+~~~~~~~~~~~~~~~~~
 
-Post-quantum key encapsulation scheme based on (structured) lattices.
+Post-quantum key encapsulation scheme based on (structured) lattices. This
+algorithm is standardized in FIPS 203. Decapsulation keys are always stored and
+expanded from the 64-byte private random seeds (``d || z``), loading the
+expanded key format specified in FIPS 203 is explicitly not supported.
 
-.. note::
+Support for ML-KEM is implemented in the module ``ml_kem``.
+
+Additionally, support for the pre-standardized version "Kyber" is retained for
+the time being. The implemented specification is commonly referred to as version
+3.01 of the CRYSTALS-Kyber submission to NIST's third round of the PQC
+competition. This is not compatible to the "Initial Public Draft" version of
+FIPS 203 for which Botan does not offer an implementation.
 
-   Currently two modes for Kyber are defined: the round3 specification
-   from the NIST PQC competition, and the "90s mode" (which uses
-   AES/SHA-2 instead of SHA-3 based primitives). The 90s mode Kyber is
-   deprecated and will be removed in a future release.
+Currently two flavors of Kyber are implemented in separate Botan modules:
 
-   The final NIST specification version of Kyber is not yet implemented.
+ * ``kyber``, that uses Keccak (SHAKE and SHA-3), and that saw some public
+   usage by early adopters.
+ * ``kyber_90s``, that uses AES/SHA-2 instead of Keccak-based primitives.
+   This mode is deprecated and will be removed in a future release.
 
 Ed25519 and Ed448
 ~~~~~~~~~~~~~~~~~
@@ -1160,18 +1169,19 @@ encapsulated key and returns the shared secret.
 Botan implements the following KEM schemes:
 
 1. RSA
-#. Kyber
+#. ML-KEM (Kyber)
 #. FrodoKEM
 #. McEliece
 
-.. _kyber_example:
+.. _mlkem_example:
 
-Code Example: Kyber
+Code Example: ML-KEM
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The code below demonstrates key encapsulation using the Kyber post-quantum scheme.
+The code below demonstrates key encapsulation using ML-KEM (FIPS 203), formerly
+known as Kyber.
 
-.. literalinclude:: /../src/examples/kyber.cpp
+.. literalinclude:: /../src/examples/ml_kem.cpp
    :language: cpp
 
 .. _mceliece:

doc/index.rst

@@ -28,7 +28,7 @@ are listed below:
 * :ref:`PBKDFs <pbkdf_example>`
 * :ref:`Key Agreement <ecdh_example>`
 * :ref:`ECDSA <ecdsa_example>`
-* :ref:`Kyber <kyber_example>`
+* :ref:`ML-KEM <mlkem_example>`
 * :ref:`RSA <rsa_example>`
 * :ref:`XMSS <xmss_example>`
 * :ref:`Stream Ciphers <stream_ciphers_example>`

readme.rst

@@ -103,7 +103,7 @@ Public Key Cryptography
 * 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 key agreement schemes McEliece, Kyber, and FrodoKEM
+* Post-quantum key agreement schemes McEliece, ML-KEM (Kyber), and FrodoKEM
 * ElGamal encryption
 * Padding schemes OAEP, PSS, PKCS #1 v1.5, X9.31
 

src/examples/hybrid_key_encapsulation.cpp

@@ -372,12 +372,12 @@ int main() {
 
    // Alice generates two key pairs suitable for:
    //   1) key exchange (X25519), and
-   //   2) key encapsulation (Kyber).
+   //   2) key encapsulation (ML-KEM).
    //
    // She then combines them into a custom "hybrid" key pair that acts
    // like a key encapsulation mechanism (KEM).
    const auto private_key_of_alice = std::make_unique<Hybrid_PrivateKey>(
-      Botan::create_private_key("X25519", rng), Botan::create_private_key("Kyber", rng, "Kyber-768-r3"));
+      Botan::create_private_key("X25519", rng), Botan::create_private_key("ML-KEM", rng, "ML-KEM-768"));
    const auto public_key_of_alice = private_key_of_alice->public_key();
 
    // Bob uses Alice's public key to encapsulate a shared secret, and

src/examples/kyber.cpp → src/examples/ml_kem.cpp

@@ -13,7 +13,7 @@ int main() {
    std::array<uint8_t, 16> salt;
    rng.randomize(salt);
 
-   Botan::Kyber_PrivateKey priv_key(rng, Botan::KyberMode::Kyber512_R3);
+   Botan::Kyber_PrivateKey priv_key(rng, Botan::KyberMode::ML_KEM_768);
    auto pub_key = priv_key.public_key();
 
    Botan::PK_KEM_Encryptor enc(*pub_key, kdf);

src/lib/utils/types.h

@@ -57,7 +57,7 @@ namespace Botan {
 *        @ref dlies.h "DLIES", @ref ecies.h "ECIES", @ref elgamal.h "ElGamal",
 *        @ref rsa.h "RSA", @ref mceliece.h "McEliece", @ref sm2.h "SM2"
 * <dt>Key Encapsulation Mechanisms<dd>
-*        @ref frodokem.h "FrodoKEM", @ref kyber.h "Kyber", @ref rsa.h "RSA"
+*        @ref frodokem.h "FrodoKEM", @ref kyber.h "ML-KEM/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 eckcdsa.h "ECKCDSA", @ref gost_3410.h "GOST 34.10-2001", @ref hss_lms.h "HSS/LMS", @ref sm2.h "SM2",