Integration of HSS-LMS

Integration into pk_algs, tests and documentation. Co-authored-by: Philippe Lieser <[email protected]> Co-authored-by: René Meusel <[email protected]>
randombit · Apr 23, 2024 · 10ec77a · 10ec77a
1 parent 17c46a9
commit 10ec77a
Show file tree

Hide file tree

Showing 9 changed files with 138 additions and 5 deletions.
diff --git a/doc/api_ref/pubkey.rst b/doc/api_ref/pubkey.rst
@@ -123,6 +123,13 @@ signatures can be created. If the same state is ever used to generate two
 signatures, then the whole scheme becomes insecure, and signatures can be
 forged.
 
+HSS-LMS
+-------
+
+A post-quantum secure hash-based signature scheme similar to XMSS. Contains
+support for multitrees. It is stateful, meaning the private key changes after
+each signature.
+
 SPHINCS+
 ~~~~~~~~~
 
@@ -782,6 +789,7 @@ Botan implements the following signature algorithms:
 #. SPHINCS+.
    Takes the optional parameter ``Deterministic`` (default) or ``Randomized``.
 #. XMSS. Takes no parameter.
+#. HSS-LMS. Takes no parameter.
 
 .. _ecdsa_example:
 
@@ -1241,3 +1249,42 @@ signature:
 
 .. literalinclude:: /../src/examples/xmss.cpp
    :language: cpp
+
+
+Hierarchical Signature System with Leighton-Micali Hash-Based Signatures (HSS-LMS)
+----------------------------------------------------------------------------------
+
+HSS-LMS is a stateful hash-based signature scheme which is defined in `RFC 8554
+"Leighton-Micali Hash-Based Signatures" <https://datatracker.ietf.org/doc/html/rfc8554>`_.
+
+It is a multitree scheme, which is highly configurable. Multitree means, it consists
+of multiple layers of Merkle trees, which can be defined individually. Moreover, the
+used hash function and the Winternitz Parameter of the underlying one-time signature
+can be chosen for each tree layer. For a sensible selection of parameters refer to
+`RFC 8554 Section 6.4. <https://datatracker.ietf.org/doc/html/rfc8554#section-6.4>`_.
+
+.. warning::
+
+   HSS-LMS is stateful, meaning the private key must be updated after
+   each signature. If the same private key is ever used to generate
+   two different signatures, then the scheme becomes insecure. For
+   this reason it can be challening to use HSS-LMS securely.
+
+HSS-LMS uses the Botan interfaces for public key cryptography. The ``params``
+argument of the HSS-LMS private key is used to define the parameter set.
+The syntax of this argument must be the following:
+
+``HSS-LMS(<hash>,HW(<h>,<w>),HW(<h>,<w>),...)``
+
+e.g. ``HSS-LMS(SHA-256,HW(5,1),HW(5,1))`` to use SHA-256 in a two-layer HSS instance
+with LMS tree height 5 and Winternitz parameter 1. This results in a
+private key that can be used to create up to 2^(5+5)=1024 signatures.
+
+The following parameters are allowed (which are specified in
+`RFC 8554 <https://datatracker.ietf.org/doc/html/rfc8554>`_ and
+and `draft-fluhrer-lms-more-parm-sets-11 <https://datatracker.ietf.org/doc/html/draft-fluhrer-lms-more-parm-sets-11>`_):
+
+- hash: ``SHA-256``, ``Truncated(SHA-256,192)``, ``SHAKE-256(256)``, ``SHAKE-256(192)``
+- h: ``5``, ``10``, ``15``, ``20``, ``25``
+- w: ``1``, ``2``, ``4``, ``8``
+
diff --git a/doc/dev_ref/oids.rst b/doc/dev_ref/oids.rst
@@ -84,6 +84,8 @@ Values currently assigned are::
   SphincsPlus-haraka-256s-r3.1 OBJECT IDENTIFIER ::= { SphincsPlus-haraka 5 }
   SphincsPlus-haraka-256f-r3.1  OBJECT IDENTIFIER ::= { SphincsPlus-haraka 6 }
 
+  HSS-LMS-Private-Key OBJECT IDENTIFIER ::= { publicKey 13 }
+
   symmetricKey OBJECT IDENTIFIER ::= { randombit 3 }
 
   ocbModes OBJECT IDENTIFIER ::= { symmetricKey 2 }

diff --git a/src/build-data/oids.txt b/src/build-data/oids.txt
@@ -1,5 +1,5 @@
-# Regenerate with ./src/scripts/dev_tools/oids.py oids > src/lib/asn1/oid_maps.cpp
-# AND             ./src/scripts/dev_tools/oids.py dn_ub > src/lib/x509/x509_dn_ub.cpp
+# Regenerate with ./src/scripts/dev_tools/gen_oids.py oids > src/lib/asn1/oid_maps.cpp
+# AND             ./src/scripts/dev_tools/gen_oids.py dn_ub > src/lib/x509/x509_dn_ub.cpp
 # (if you modified something under [dn]
 
 # Public key types
@@ -47,6 +47,14 @@
 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
 
+# HSS-LMS
+# draft-gazdag-x509-hash-sigs-01
+1.2.840.113549.1.9.16.3.17 = HSS-LMS
+
+# HSS-LMS private key (since the format of an HSS-LMS private key is not specified,
+#  we define an OID for the one we use)
+1.3.6.1.4.1.25258.1.13 = HSS-LMS-Private-Key
+
 # SPHINCS+ OIDs are currently in Botan's private arc
 1.3.6.1.4.1.25258.1.12.1.1 = SphincsPlus-shake-128s-r3.1
 1.3.6.1.4.1.25258.1.12.1.2 = SphincsPlus-shake-128f-r3.1

diff --git a/src/cli/speed.cpp b/src/cli/speed.cpp
@@ -124,6 +124,10 @@
    #include <botan/dilithium.h>
 #endif
 
+#if defined(BOTAN_HAS_HSS_LMS)
+   #include <botan/hss_lms.h>
+#endif
+
 #if defined(BOTAN_HAS_SPHINCS_PLUS_WITH_SHA2) || defined(BOTAN_HAS_SPHINCS_PLUS_WITH_SHAKE)
    #include <botan/sphincsplus.h>
 #endif
@@ -411,7 +415,8 @@ class Speed final : public Command {
             "McEliece",
             "Kyber",
             "SPHINCS+",
-            "FrodoKEM"
+            "FrodoKEM",
+            "HSS-LMS",
          };
          // clang-format on
       }
@@ -626,6 +631,11 @@ class Speed final : public Command {
                bench_xmss(provider, msec);
             }
 #endif
+#if defined(BOTAN_HAS_HSS_LMS)
+            else if(algo == "HSS-LMS") {
+               bench_hss_lms(provider, msec);
+            }
+#endif
 #if defined(BOTAN_HAS_SPHINCS_PLUS_WITH_SHA2) || defined(BOTAN_HAS_SPHINCS_PLUS_WITH_SHAKE)
             else if(algo == "SPHINCS+") {
                bench_sphincs_plus(provider, msec);
@@ -2134,6 +2144,33 @@ class Speed final : public Command {
       }
 #endif
 
+#if defined(BOTAN_HAS_HSS_LMS)
+      void bench_hss_lms(const std::string& provider, std::chrono::milliseconds msec) {
+         // At first we compare instances with multiple hash functions. LMS trees with
+         // height 10 are suitable, since they can be used for enough signatures and are
+         // fast enough for speed testing.
+         // Afterward, setups with multiple HSS layers are tested
+         std::vector<std::string> hss_lms_instances{"SHA-256,HW(10,1)",
+                                                    "SHAKE-256(256),HW(10,1)",
+                                                    "SHAKE-256(192),HW(10,1)",
+                                                    "Truncated(SHA-256,192),HW(10,1)",
+                                                    "SHA-256,HW(10,1),HW(10,1)",
+                                                    "SHA-256,HW(10,1),HW(10,1),HW(10,1)"};
+
+         for(const auto& params : hss_lms_instances) {
+            auto keygen_timer = make_timer(params, provider, "keygen");
+
+            std::unique_ptr<Botan::Private_Key> key(
+               keygen_timer->run([&] { return Botan::create_private_key("HSS-LMS", rng(), params); }));
+
+            record_result(keygen_timer);
+            if(bench_pk_sig(*key, params, provider, "", msec) == 1) {
+               break;
+            }
+         }
+      }
+#endif
+
 #if defined(BOTAN_HAS_ZFEC)
       void bench_zfec(std::chrono::milliseconds msec) {
          const size_t k = 4;

diff --git a/src/lib/asn1/oid_maps.cpp b/src/lib/asn1/oid_maps.cpp
@@ -91,6 +91,7 @@ std::unordered_map<std::string, std::string> OID_Map::load_oid2str_map() {
       {"1.2.840.113549.1.5.13", "PBE-PKCS5v20"},
       {"1.2.840.113549.1.9.1", "PKCS9.EmailAddress"},
       {"1.2.840.113549.1.9.14", "PKCS9.ExtensionRequest"},
+      {"1.2.840.113549.1.9.16.3.17", "HSS-LMS"},
       {"1.2.840.113549.1.9.16.3.18", "ChaCha20Poly1305"},
       {"1.2.840.113549.1.9.16.3.6", "KeyWrap.TripleDES"},
       {"1.2.840.113549.1.9.16.3.8", "Compression.Zlib"},
@@ -164,6 +165,7 @@ std::unordered_map<std::string, std::string> OID_Map::load_oid2str_map() {
       {"1.3.6.1.4.1.25258.1.12.3.4", "SphincsPlus-haraka-192f-r3.1"},
       {"1.3.6.1.4.1.25258.1.12.3.5", "SphincsPlus-haraka-256s-r3.1"},
       {"1.3.6.1.4.1.25258.1.12.3.6", "SphincsPlus-haraka-256f-r3.1"},
+      {"1.3.6.1.4.1.25258.1.13", "HSS-LMS-Private-Key"},
       {"1.3.6.1.4.1.25258.1.14.1", "FrodoKEM-640-SHAKE"},
       {"1.3.6.1.4.1.25258.1.14.2", "FrodoKEM-976-SHAKE"},
       {"1.3.6.1.4.1.25258.1.14.3", "FrodoKEM-1344-SHAKE"},
@@ -405,6 +407,8 @@ std::unordered_map<std::string, OID> OID_Map::load_str2oid_map() {
       {"HMAC(SHA-384)", OID({1, 2, 840, 113549, 2, 10})},
       {"HMAC(SHA-512)", OID({1, 2, 840, 113549, 2, 11})},
       {"HMAC(SHA-512-256)", OID({1, 2, 840, 113549, 2, 13})},
+      {"HSS-LMS", OID({1, 2, 840, 113549, 1, 9, 16, 3, 17})},
+      {"HSS-LMS-Private-Key", OID({1, 3, 6, 1, 4, 1, 25258, 1, 13})},
       {"KeyWrap.AES-128", OID({2, 16, 840, 1, 101, 3, 4, 1, 5})},
       {"KeyWrap.AES-192", OID({2, 16, 840, 1, 101, 3, 4, 1, 25})},
       {"KeyWrap.AES-256", OID({2, 16, 840, 1, 101, 3, 4, 1, 45})},

diff --git a/src/lib/pubkey/pk_algs.cpp b/src/lib/pubkey/pk_algs.cpp
@@ -82,6 +82,10 @@
    #include <botan/kyber.h>
 #endif
 
+#if defined(BOTAN_HAS_HSS_LMS)
+   #include <botan/hss_lms.h>
+#endif
+
 #if defined(BOTAN_HAS_XMSS_RFC8391)
    #include <botan/xmss.h>
 #endif
@@ -220,6 +224,12 @@ std::unique_ptr<Public_Key> load_public_key(const AlgorithmIdentifier& alg_id,
    }
 #endif
 
+#if defined(BOTAN_HAS_HSS_LMS)
+   if(alg_name == "HSS-LMS") {
+      return std::make_unique<HSS_LMS_PublicKey>(key_bits);
+   }
+#endif
+
 #if defined(BOTAN_HAS_SPHINCS_PLUS_WITH_SHA2) || defined(BOTAN_HAS_SPHINCS_PLUS_WITH_SHAKE)
    if(alg_name == "SPHINCS+" || alg_name.starts_with("SphincsPlus-")) {
       return std::make_unique<SphincsPlus_PublicKey>(alg_id, key_bits);
@@ -349,6 +359,12 @@ std::unique_ptr<Private_Key> load_private_key(const AlgorithmIdentifier& alg_id,
    }
 #endif
 
+#if defined(BOTAN_HAS_HSS_LMS)
+   if(alg_name == "HSS-LMS-Private-Key") {
+      return std::make_unique<HSS_LMS_PrivateKey>(key_bits);
+   }
+#endif
+
 #if defined(BOTAN_HAS_SPHINCS_PLUS_WITH_SHA2) || defined(BOTAN_HAS_SPHINCS_PLUS_WITH_SHAKE)
    if(alg_name == "SPHINCS+" || alg_name.starts_with("SphincsPlus-")) {
       return std::make_unique<SphincsPlus_PrivateKey>(alg_id, key_bits);
@@ -485,6 +501,12 @@ std::unique_ptr<Private_Key> create_private_key(std::string_view alg_name,
    }
 #endif
 
+#if defined(BOTAN_HAS_HSS_LMS)
+   if(alg_name == "HSS-LMS") {
+      return std::make_unique<HSS_LMS_PrivateKey>(rng, params);
+   }
+#endif
+
 #if defined(BOTAN_HAS_SPHINCS_PLUS_WITH_SHA2) || defined(BOTAN_HAS_SPHINCS_PLUS_WITH_SHAKE)
    if(alg_name == "SPHINCS+" || alg_name == "SphincsPlus-") {
       auto sphincs_params = Sphincs_Parameters::create(params);

diff --git a/src/lib/x509/x509_obj.cpp b/src/lib/x509/x509_obj.cpp
@@ -173,6 +173,9 @@ std::string x509_signature_padding_for(const std::string& algo_name,
    } else if(algo_name == "XMSS") {
       // XMSS does not take any padding, but if the user insists, we pass it along
       return std::string(user_specified_padding);
+   } else if(algo_name == "HSS-LMS") {
+      // HSS-LMS does not take any padding, but if the user insists, we pass it along
+      return std::string(user_specified_padding);
    } else {
       throw Invalid_Argument("Unknown X.509 signing key type: " + algo_name);
    }

diff --git a/src/tests/data/pubkey/api_sign.vec b/src/tests/data/pubkey/api_sign.vec
@@ -36,6 +36,11 @@ SigParams = Ed25519ph
 AlgoParams = gost_256A
 SigParams = Raw
 
+[HSS-LMS]
+
+AlgoParams = SHA-256,HW(5,8)
+SigParams =
+
 [RSA]
 
 AlgoParams = 2048

diff --git a/src/tests/unit_x509.cpp b/src/tests/unit_x509.cpp
@@ -109,6 +109,9 @@ std::unique_ptr<Botan::Private_Key> make_a_private_key(const std::string& algo,
       if(algo == "ECKCDSA" || algo == "ECGDSA") {
          return "brainpool256r1";
       }
+      if(algo == "HSS-LMS") {
+         return "SHA-256,HW(5,4),HW(5,4)";
+      }
       return "";  // default "" means choose acceptable algo-specific params
    }();
 
@@ -1218,7 +1221,7 @@ Test::Result test_valid_constraints(const Botan::Private_Key& key, const std::st
       result.test_eq("crl sign not permitted", crl_sign.compatible_with(key), false);
       result.test_eq("sign", sign_everything.compatible_with(key), false);
    } else if(pk_algo == "DSA" || pk_algo == "ECDSA" || pk_algo == "ECGDSA" || pk_algo == "ECKCDSA" ||
-             pk_algo == "GOST-34.10" || pk_algo == "Dilithium") {
+             pk_algo == "GOST-34.10" || pk_algo == "Dilithium" || pk_algo == "HSS-LMS") {
       // these are signature algorithms only
       result.test_eq("all constraints not permitted", all.compatible_with(key), false);
 
@@ -1510,6 +1513,8 @@ std::vector<std::string> get_sig_paddings(const std::string& sig_algo, const std
       return {"Pure"};
    } else if(sig_algo == "Dilithium") {
       return {"Randomized"};
+   } else if(sig_algo == "HSS-LMS") {
+      return {""};
    } else {
       return {};
    }
@@ -1523,7 +1528,7 @@ class X509_Cert_Unit_Tests final : public Test {
          auto& rng = this->rng();
 
          const std::string sig_algos[]{
-            "RSA", "DSA", "ECDSA", "ECGDSA", "ECKCDSA", "GOST-34.10", "Ed25519", "Ed448", "Dilithium"};
+            "RSA", "DSA", "ECDSA", "ECGDSA", "ECKCDSA", "GOST-34.10", "Ed25519", "Ed448", "Dilithium", "HSS-LMS"};
 
          for(const std::string& algo : sig_algos) {
    #if !defined(BOTAN_HAS_EMSA_PKCS1)