ML-KEM (Initial Public Draft)

This adds ML-KEM-ipd as new modes in the Kyber implementation. It also integrates the new algorithm into the library's higher level APIs under the name "ML-KEM-ipd". Currently, neither TLS nor the FFI layer support it.
randombit · Jan 18, 2024 · 8c19232 · 8c19232
1 parent 3f8a8cf
commit 8c19232
Show file tree

Hide file tree

Showing 17 changed files with 819 additions and 43 deletions.
diff --git a/doc/api_ref/pubkey.rst b/doc/api_ref/pubkey.rst
@@ -106,7 +106,16 @@ Post-quantum key encapsulation scheme based on (structured) lattices.
    AES/SHA-2 instead of SHA-3 based primitives). The 90s mode Kyber is
    deprecated and will be removed in a future release.
 
-   The final NIST specification version of Kyber is not yet implemented.
+ML-KEM (Initial Public Draft)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Post-quantum key encapsulation scheme based on (structured) lattices.
+
+.. note::
+
+   ML-KEM is currently a draft (NIST FIPS 203). It is not yet standardized,
+   and neither long-term interoperability nor support is guaranteed.
+
 
 Ed25519
 ~~~~~~~~~~

diff --git a/src/build-data/oids.txt b/src/build-data/oids.txt
@@ -35,6 +35,12 @@
 1.3.6.1.4.1.25258.1.11.2 = Kyber-768-90s-r3
 1.3.6.1.4.1.25258.1.11.3 = Kyber-1024-90s-r3
 
+# ML-KEM Initial Public Draft - Bouncy Castle's private OIDs
+# (taken from the IETF hackathon: https://github.com/IETF-Hackathon/pqc-certificates/blob/f9ecf761c3b4f3a84520536b7ce3175e8c7726fd/docs/oid_mapping.md#nist-draft-standard-algorithm-oids)
+1.3.6.1.4.1.22554.5.6.1 = ML-KEM-512-ipd
+1.3.6.1.4.1.22554.5.6.2 = ML-KEM-768-ipd
+1.3.6.1.4.1.22554.5.6.3 = ML-KEM-1024-ipd
+
 # Dilithium OIDs are currently in Botan's private arc
 1.3.6.1.4.1.25258.1.9.1 = Dilithium-4x4-r3
 1.3.6.1.4.1.25258.1.9.2 = Dilithium-6x5-r3

diff --git a/src/cli/speed.cpp b/src/cli/speed.cpp
@@ -116,7 +116,7 @@
    #include <botan/mceliece.h>
 #endif
 
-#if defined(BOTAN_HAS_KYBER) || defined(BOTAN_HAS_KYBER_90S)
+#if defined(BOTAN_HAS_KYBER) || defined(BOTAN_HAS_KYBER_90S) || defined(BOTAN_HAS_ML_KEM_INITIAL_PUBLIC_DRAFT)
    #include <botan/kyber.h>
 #endif
 
@@ -408,6 +408,7 @@ class Speed final : public Command {
             "Curve25519",
             "McEliece",
             "Kyber",
+            "ML-KEM-ipd",
             "SPHINCS+",
             "FrodoKEM"
          };
@@ -601,7 +602,27 @@ class Speed final : public Command {
 #endif
 #if defined(BOTAN_HAS_KYBER) || defined(BOTAN_HAS_KYBER_90S)
             else if(algo == "Kyber") {
-               bench_kyber(provider, msec);
+               bench_kyber(provider,
+                           msec,
+                           {
+                              Botan::KyberMode::Kyber512_R3,
+                              Botan::KyberMode::Kyber512_90s,
+                              Botan::KyberMode::Kyber768_R3,
+                              Botan::KyberMode::Kyber768_90s,
+                              Botan::KyberMode::Kyber1024_R3,
+                              Botan::KyberMode::Kyber1024_90s,
+                           });
+            }
+#endif
+#if defined(BOTAN_HAS_ML_KEM_INITIAL_PUBLIC_DRAFT)
+            else if(algo == "ML-KEM-ipd") {
+               bench_kyber(provider,
+                           msec,
+                           {
+                              Botan::KyberMode::ML_KEM_512_ipd,
+                              Botan::KyberMode::ML_KEM_768_ipd,
+                              Botan::KyberMode::ML_KEM_1024_ipd,
+                           });
             }
 #endif
 #if defined(BOTAN_HAS_DILITHIUM) || defined(BOTAN_HAS_DILITHIUM_AES)
@@ -1946,27 +1967,28 @@ class Speed final : public Command {
 #endif
 
 #if defined(BOTAN_HAS_KYBER) || defined(BOTAN_HAS_KYBER_90S)
-      void bench_kyber(const std::string& provider, std::chrono::milliseconds msec) {
-         const Botan::KyberMode::Mode all_modes[] = {
-            Botan::KyberMode::Kyber512_R3,
-            Botan::KyberMode::Kyber512_90s,
-            Botan::KyberMode::Kyber768_R3,
-            Botan::KyberMode::Kyber768_90s,
-            Botan::KyberMode::Kyber1024_R3,
-            Botan::KyberMode::Kyber1024_90s,
-         };
-
+      void bench_kyber(const std::string& provider,
+                       std::chrono::milliseconds msec,
+                       const std::vector<Botan::KyberMode::Mode>& all_modes) {
          for(auto modet : all_modes) {
             Botan::KyberMode mode(modet);
 
    #if !defined(BOTAN_HAS_KYBER)
-            if(mode.is_modern())
+            if(mode.is_kyber_r3() && mode.is_modern()) {
                continue;
+            }
    #endif
 
    #if !defined(BOTAN_HAS_KYBER_90S)
-            if(mode.is_90s())
+            if(mode.is_kyber_r3() && mode.is_90s()) {
                continue;
+            }
+   #endif
+
+   #if !defined(BOTAN_HAS_ML_KEM_INITIAL_PUBLIC_DRAFT)
+            if(mode.is_ml_kem_ipd()) {
+               continue;
+            }
    #endif
 
             auto keygen_timer = make_timer(mode.to_string(), provider, "keygen");

diff --git a/src/lib/asn1/oid_maps.cpp b/src/lib/asn1/oid_maps.cpp
@@ -1,7 +1,7 @@
 /*
 * OID maps
 *
-* This file was automatically generated by ./src/scripts/dev_tools/gen_oids.py on 2023-11-02
+* This file was automatically generated by ./src/scripts/dev_tools/gen_oids.py on 2024-01-18
 *
 * All manual edits to this file will be lost. Edit the script
 * then regenerate this source file.
@@ -138,6 +138,9 @@ std::unordered_map<std::string, std::string> OID_Map::load_oid2str_map() {
       {"1.3.36.3.3.2.8.1.1.9", "brainpool320r1"},
       {"1.3.6.1.4.1.11591.15.1", "OpenPGP.Ed25519"},
       {"1.3.6.1.4.1.11591.4.11", "Scrypt"},
+      {"1.3.6.1.4.1.22554.5.6.1", "ML-KEM-512-ipd"},
+      {"1.3.6.1.4.1.22554.5.6.2", "ML-KEM-768-ipd"},
+      {"1.3.6.1.4.1.22554.5.6.3", "ML-KEM-1024-ipd"},
       {"1.3.6.1.4.1.25258.1.10.1", "Dilithium-4x4-AES-r3"},
       {"1.3.6.1.4.1.25258.1.10.2", "Dilithium-6x5-AES-r3"},
       {"1.3.6.1.4.1.25258.1.10.3", "Dilithium-8x7-AES-r3"},
@@ -415,6 +418,9 @@ std::unordered_map<std::string, OID> OID_Map::load_str2oid_map() {
       {"Kyber-768-r3", OID({1, 3, 6, 1, 4, 1, 25258, 1, 7, 2})},
       {"MD5", OID({1, 2, 840, 113549, 2, 5})},
       {"MGF1", OID({1, 2, 840, 113549, 1, 1, 8})},
+      {"ML-KEM-1024-ipd", OID({1, 3, 6, 1, 4, 1, 22554, 5, 6, 3})},
+      {"ML-KEM-512-ipd", OID({1, 3, 6, 1, 4, 1, 22554, 5, 6, 1})},
+      {"ML-KEM-768-ipd", OID({1, 3, 6, 1, 4, 1, 22554, 5, 6, 2})},
       {"McEliece", OID({1, 3, 6, 1, 4, 1, 25258, 1, 3})},
       {"Microsoft SmartcardLogon", OID({1, 3, 6, 1, 4, 1, 311, 20, 2, 2})},
       {"Microsoft UPN", OID({1, 3, 6, 1, 4, 1, 311, 20, 2, 3})},

diff --git a/src/lib/pubkey/kyber/kyber_common/kyber.cpp b/src/lib/pubkey/kyber/kyber_common/kyber.cpp
@@ -38,6 +38,10 @@
    #include <botan/internal/kyber_encaps.h>
 #endif
 
+#if defined(BOTAN_HAS_ML_KEM_INITIAL_PUBLIC_DRAFT)
+   #include <botan/internal/ml_kem_ipd.h>
+#endif
+
 #include <array>
 #include <limits>
 #include <memory>
@@ -66,6 +70,15 @@ KyberMode::Mode kyber_mode_from_string(std::string_view str) {
    if(str == "Kyber-1024-r3") {
       return KyberMode::Kyber1024_R3;
    }
+   if(str == "ML-KEM-512-ipd") {
+      return KyberMode::ML_KEM_512_ipd;
+   }
+   if(str == "ML-KEM-768-ipd") {
+      return KyberMode::ML_KEM_768_ipd;
+   }
+   if(str == "ML-KEM-1024-ipd") {
+      return KyberMode::ML_KEM_1024_ipd;
+   }
 
    throw Invalid_Argument(fmt("'{}' is not a valid Kyber mode name", str));
 }
@@ -96,6 +109,12 @@ std::string KyberMode::to_string() const {
          return "Kyber-768-r3";
       case Kyber1024_R3:
          return "Kyber-1024-r3";
+      case ML_KEM_512_ipd:
+         return "ML-KEM-512-ipd";
+      case ML_KEM_768_ipd:
+         return "ML-KEM-768-ipd";
+      case ML_KEM_1024_ipd:
+         return "ML-KEM-1024-ipd";
    }
 
    BOTAN_ASSERT_UNREACHABLE();
@@ -109,6 +128,11 @@ bool KyberMode::is_modern() const {
    return !is_90s();
 }
 
+bool KyberMode::is_ml_kem_ipd() const {
+   return m_mode == KyberMode::ML_KEM_512_ipd || m_mode == KyberMode::ML_KEM_768_ipd ||
+          m_mode == KyberMode::ML_KEM_1024_ipd;
+}
+
 bool KyberMode::is_kyber_round3() const {
    return m_mode == KyberMode::Kyber512_R3 || m_mode == KyberMode::Kyber768_R3 || m_mode == KyberMode::Kyber1024_R3 ||
           m_mode == KyberMode::Kyber512_90s || m_mode == KyberMode::Kyber768_90s || m_mode == KyberMode::Kyber1024_90s;
@@ -127,6 +151,12 @@ bool KyberMode::is_available() const {
    }
 #endif
 
+#if defined(BOTAN_HAS_ML_KEM_INITIAL_PUBLIC_DRAFT)
+   if(is_ml_kem_ipd()) {
+      return true;
+   }
+#endif
+
    return false;
 }
 
@@ -135,7 +165,7 @@ KyberMode Kyber_PublicKey::mode() const {
 }
 
 std::string Kyber_PublicKey::algo_name() const {
-   return "Kyber";
+   return mode().is_ml_kem_ipd() ? "ML-KEM-ipd" : "Kyber";
 }
 
 AlgorithmIdentifier Kyber_PublicKey::algorithm_identifier() const {
@@ -275,6 +305,12 @@ std::unique_ptr<PK_Ops::KEM_Encryption> Kyber_PublicKey::create_kem_encryption_o
       }
 #endif
 
+#if defined(BOTAN_HAS_ML_KEM_INITIAL_PUBLIC_DRAFT)
+      if(mode().is_ml_kem_ipd()) {
+         return std::make_unique<ML_KEM_IPD_Encryptor>(m_public, params);
+      }
+#endif
+
       BOTAN_ASSERT_UNREACHABLE();
    }
    throw Provider_Not_Found(algo_name(), provider);
@@ -291,6 +327,12 @@ std::unique_ptr<PK_Ops::KEM_Decryption> Kyber_PrivateKey::create_kem_decryption_
       }
 #endif
 
+#if defined(BOTAN_HAS_ML_KEM_INITIAL_PUBLIC_DRAFT)
+      if(mode().is_ml_kem_ipd()) {
+         return std::make_unique<ML_KEM_IPD_Decryptor>(m_private, m_public, params);
+      }
+#endif
+
       BOTAN_ASSERT_UNREACHABLE();
    }
    throw Provider_Not_Found(algo_name(), provider);

diff --git a/src/lib/pubkey/kyber/kyber_common/kyber.h b/src/lib/pubkey/kyber/kyber_common/kyber.h
@@ -21,8 +21,10 @@
 
 #include <span>
 
-#if !defined(BOTAN_HAS_KYBER_90S) && !defined(BOTAN_HAS_KYBER)
-static_assert(false, "botan module 'kyber_common' is useful only when enabling modules 'kyber', 'kyber_90s' or both");
+#if !defined(BOTAN_HAS_KYBER_90S) && !defined(BOTAN_HAS_KYBER) && !defined(BOTAN_HAS_ML_KEM_INITIAL_PUBLIC_DRAFT)
+static_assert(
+   false,
+   "botan module 'kyber_common' is useful only when enabling at least one of those modules: 'kyber', 'kyber_90s', 'ml_kem_ipd'");
 #endif
 
 namespace Botan {
@@ -41,6 +43,13 @@ class BOTAN_PUBLIC_API(3, 0) KyberMode {
          Kyber768 BOTAN_DEPRECATED("Use Kyber768_R3") = Kyber768_R3,
          Kyber1024 BOTAN_DEPRECATED("Use Kyber1024_R3") = Kyber1024_R3,
 
+         // ML-KEM as proposed by NIST in the initial public draft of the standard
+         ML_KEM_512_ipd,
+         // ML-KEM as proposed by NIST in the initial public draft of the standard
+         ML_KEM_768_ipd,
+         // ML-KEM as proposed by NIST in the initial public draft of the standard
+         ML_KEM_1024_ipd,
+
          Kyber512_90s BOTAN_DEPRECATED("Kyber 90s mode is deprecated"),
          Kyber768_90s BOTAN_DEPRECATED("Kyber 90s mode is deprecated"),
          Kyber1024_90s BOTAN_DEPRECATED("Kyber 90s mode is deprecated"),
@@ -59,6 +68,8 @@ class BOTAN_PUBLIC_API(3, 0) KyberMode {
 
       BOTAN_DEPRECATED("Kyber 90s mode is deprecated") bool is_modern() const;
 
+      bool is_ml_kem_ipd() const;
+
       bool is_kyber_round3() const;
 
       bool is_available() const;

diff --git a/src/lib/pubkey/kyber/kyber_common/kyber_constants.cpp b/src/lib/pubkey/kyber/kyber_common/kyber_constants.cpp
@@ -19,26 +19,33 @@
    #include <botan/internal/kyber_90s.h>
 #endif
 
+#if defined(BOTAN_HAS_ML_KEM_INITIAL_PUBLIC_DRAFT)
+   #include <botan/internal/ml_kem_ipd.h>
+#endif
+
 namespace Botan {
 
 KyberConstants::KyberConstants(KyberMode mode) : m_mode(mode) {
    switch(mode.mode()) {
       case KyberMode::Kyber512_R3:
       case KyberMode::Kyber512_90s:
+      case KyberMode::ML_KEM_512_ipd:
          m_nist_strength = 128;
          m_k = 2;
          m_eta1 = 3;
          break;
 
       case KyberMode::Kyber768_R3:
       case KyberMode::Kyber768_90s:
+      case KyberMode::ML_KEM_768_ipd:
          m_nist_strength = 192;
          m_k = 3;
          m_eta1 = 2;
          break;
 
       case KyberMode::Kyber1024_R3:
       case KyberMode::Kyber1024_90s:
+      case KyberMode::ML_KEM_1024_ipd:
          m_nist_strength = 256;
          m_k = 4;
          m_eta1 = 2;
@@ -60,6 +67,12 @@ KyberConstants::KyberConstants(KyberMode mode) : m_mode(mode) {
    }
 #endif
 
+#ifdef BOTAN_HAS_ML_KEM_INITIAL_PUBLIC_DRAFT
+   if(mode.is_ml_kem_ipd()) {
+      m_symmetric_primitives = std::make_unique<ML_KEM_IPD_Symmetric_Primitives>();
+   }
+#endif
+
    if(!m_symmetric_primitives) {
       throw Not_Implemented("requested Kyber mode is not enabled in this build");
    }

diff --git a/src/lib/pubkey/kyber/kyber_common/kyber_symmetric_primitives.h b/src/lib/pubkey/kyber/kyber_common/kyber_symmetric_primitives.h
@@ -54,6 +54,14 @@ class Kyber_Symmetric_Primitives {
          return G_split<KyberSharedSecret, KyberEncryptionRandomness>(msg, pubkey_hash);
       }
 
+      KyberSharedSecret J(StrongSpan<const KyberImplicitRejectionValue> rejection_value,
+                          StrongSpan<const KyberCompressedCiphertext> ciphertext) const {
+         auto& j = get_J();
+         j.update(rejection_value);
+         j.update(ciphertext);
+         return j.final<KyberSharedSecret>();
+      }
+
       // TODO: remove this once Kyber-R3 is removed
       void KDF(StrongSpan<KyberSharedSecret> out,
                StrongSpan<const KyberSharedSecret> shared_secret,
@@ -100,6 +108,7 @@ class Kyber_Symmetric_Primitives {
    protected:
       virtual HashFunction& get_G() const = 0;
       virtual HashFunction& get_H() const = 0;
+      virtual HashFunction& get_J() const = 0;
       virtual HashFunction& get_KDF() const = 0;
       virtual Botan::XOF& get_PRF(std::span<const uint8_t> seed, uint8_t nonce) const = 0;
       virtual std::unique_ptr<Botan::XOF> get_XOF(std::span<const uint8_t> seed,

diff --git a/src/lib/pubkey/kyber/kyber_round3/kyber/kyber_modern.h b/src/lib/pubkey/kyber/kyber_round3/kyber/kyber_modern.h
@@ -34,6 +34,8 @@ class Kyber_Modern_Symmetric_Primitives : public Kyber_Symmetric_Primitives {
 
       HashFunction& get_H() const override { return *m_sha3_256; }
 
+      HashFunction& get_J() const override { throw Invalid_State("Kyber-R3 does not support J()"); }
+
       HashFunction& get_KDF() const override { return *m_shake256_256; }
 
       Botan::XOF& get_PRF(std::span<const uint8_t> seed, const uint8_t nonce) const override {

diff --git a/src/lib/pubkey/kyber/kyber_round3/kyber_90s/kyber_90s.h b/src/lib/pubkey/kyber/kyber_round3/kyber_90s/kyber_90s.h
@@ -32,6 +32,8 @@ class Kyber_90s_Symmetric_Primitives : public Kyber_Symmetric_Primitives {
 
       HashFunction& get_H() const override { return *m_sha256; }
 
+      HashFunction& get_J() const override { throw Invalid_State("Kyber-R3 does not support J()"); }
+
       HashFunction& get_KDF() const override { return *m_sha256; }
 
       Botan::XOF& get_PRF(std::span<const uint8_t> seed, const uint8_t nonce) const override {

diff --git a/src/lib/pubkey/kyber/ml_kem_ipd/info.txt b/src/lib/pubkey/kyber/ml_kem_ipd/info.txt
@@ -0,0 +1,19 @@
+<defines>
+ML_KEM_INITIAL_PUBLIC_DRAFT -> 20240117
+</defines>
+
+<module_info>
+name -> "ML-KEM (IPD)"
+brief -> "Module Lattice KEM (Initial Public Draft)"
+</module_info>
+
+<requires>
+kyber_common
+sha3
+shake
+shake_xof
+</requires>
+
+<header:internal>
+ml_kem_ipd.h
+</header:internal>