Skip to content

Commit

Permalink
ML-KEM: update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
reneme committed Oct 14, 2024
1 parent eb12dcc commit a2498c1
Show file tree
Hide file tree
Showing 6 changed files with 30 additions and 20 deletions.
38 changes: 24 additions & 14 deletions doc/api_ref/pubkey.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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>`
Expand Down
2 changes: 1 addition & 1 deletion readme.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions src/examples/hybrid_key_encapsulation.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion src/examples/kyber.cpp → src/examples/ml_kem.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
2 changes: 1 addition & 1 deletion src/lib/utils/types.h
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down

0 comments on commit a2498c1

Please sign in to comment.