diff --git a/doc/api_ref/pubkey.rst b/doc/api_ref/pubkey.rst index d327accafef..059d5f265bc 100644 --- a/doc/api_ref/pubkey.rst +++ b/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: diff --git a/doc/index.rst b/doc/index.rst index 93420d68a5e..61c3ac891c5 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -28,7 +28,7 @@ are listed below: * :ref:`PBKDFs ` * :ref:`Key Agreement ` * :ref:`ECDSA ` -* :ref:`Kyber ` +* :ref:`ML-KEM ` * :ref:`RSA ` * :ref:`XMSS ` * :ref:`Stream Ciphers ` diff --git a/readme.rst b/readme.rst index 78a84229463..02cdcfdaeb5 100644 --- a/readme.rst +++ b/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 diff --git a/src/examples/hybrid_key_encapsulation.cpp b/src/examples/hybrid_key_encapsulation.cpp index 39d3a17672c..89437570565 100644 --- a/src/examples/hybrid_key_encapsulation.cpp +++ b/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( - 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 diff --git a/src/examples/kyber.cpp b/src/examples/ml_kem.cpp similarity index 91% rename from src/examples/kyber.cpp rename to src/examples/ml_kem.cpp index 5770c37e80c..261e2886e81 100644 --- a/src/examples/kyber.cpp +++ b/src/examples/ml_kem.cpp @@ -13,7 +13,7 @@ int main() { std::array 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); diff --git a/src/lib/utils/types.h b/src/lib/utils/types.h index aa2f91a19c3..fc4c8c320da 100644 --- a/src/lib/utils/types.h +++ b/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" *
Key Encapsulation Mechanisms
-* @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" *
Public Key Signature Schemes
* @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",