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
 ~~~~~~~~~~~~~~~~~
@@ -1154,18 +1163,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

@@ -355,12 +355,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",