Add SPAKE2 password authenticated key exchange (RFC 9382)

doc/api_ref/contents.rst

@@ -24,6 +24,7 @@ API Reference
    keywrap
    passhash
    cryptobox
+   spake2
    srp
    psk_db
    filters

doc/api_ref/spake2.rst

@@ -0,0 +1,80 @@
+SPAKE2 Password Authenticated Key Exchange
+=============================================
+
+.. versionadded:: 3.7.0
+
+An implementation of SPAKE2 password authenticated key exchange
+compatible with RFC 9832 is included.
+
+SPAKE2 requires each peer know its "role" within the protocol, namely being A
+or B. This is common in most protocols; for example in a client/server
+architecture, the client could be A and the server B.
+
+This implementation of SPAKE2 does not include the key confirmation step. Thus,
+on its own, there is no guarantee that the two peers actually share the same
+secret key. Normally the SPAKE2 shared secret is subsequently used to encrypt
+one or more messages; this serves to confirm the key. It is possible to
+implement RFC 9832 compatible key confirmation, as described in RFC 9832 Section 4.
+
+Each instance is configured with a set of parameters
+
+.. cpp:class:: SPAKE2_Parameters
+
+   .. cpp:function:: SPAKE2_Parameters(const EC_Group& group, \
+                        std::string_view shared_secret, \
+                        std::span<const uint8_t> a_identity = {}, \
+                        std::span<const uint8_t> b_identity = {}, \
+                        std::span<const uint8_t> context = {}, \
+                        std::string_view hash = "SHA-512", \
+                        bool per_user_params = true)
+
+      Constructs a new set of parameters.
+
+      The elliptic curve group should typically be P-256, P-384, or P-521.
+
+      The ``shared_secret`` is the low entropy user secret. This is hashed using
+      Argon2id to generate the SPAKE2 ``w`` parameter.
+
+      The identities of the two peers are specified in ``a_identity`` and
+      ``b_identity``. These can be left empty if there is no possible identity;
+      however even the strings "client" and "server" would be preferable rather
+      than leaving them completely blank.
+
+      The ``context`` is some arbitrary bytestring which is included when hashing
+      the shared secret. It can be left empty, or can be used to identity eg
+      the protocol in use.
+
+      The ``hash_fn`` parameter specifies a hash function to use. Use SHA-512.
+
+      If ``per_user_params`` is true, then SPAKE2 will proceed using system
+      parameters N/M which were generated using RFC 9380 hash to curve using the
+      identities and context string as inputs. This makes SPAKE2 "quantum
+      annoying"; baseline SPAKE2 can be broken by anyone who can recover the
+      discrete logarithms of the fixed N/M parameters included in the RFC. This
+      makes life difficult for an attacker who can compute discrete logarithms,
+      but cannot do so cheaply.
+
+.. cpp:enum-class:: SPAKE2_PeerId
+
+   .. cpp:enumerator:: SPAKE2_PeerId::PeerA
+
+   .. cpp:enumerator:: SPAKE2_PeerId::PeerB
+
+
+.. cpp:class:: SPAKE2_Context
+
+   .. cpp:function:: SPAKE2_Context(SPAKE2_PeerId whoami, \
+                     const SPAKE2_Parameters& params, \
+                     RandomNumberGenerator& rng)
+
+      Prepare for a SPAKE2 exchange
+
+   .. cpp:function:: std::vector<uint8_t> generate_message()
+
+      Proceed with the protocol. Generate a message, which must be sent
+      to the peer.
+
+   .. cpp:function:: secure_vector<uint8_t> process_message(std::span<const uint8_t> peer_message)
+
+      Complete the key exchange, returning the shared secret. Will throw an exception
+      if an error occurs (eg the peer message is not formatted correctly)

src/lib/pake/spake2/info.txt

@@ -0,0 +1,19 @@
+<defines>
+PAKE_SPAKE2 -> 20240821
+</defines>
+
+<module_info>
+name -> "SPAKE2"
+brief -> "SPAKE2 PAKE"
+</module_info>
+
+<header:public>
+spake2.h
+</header:public>
+
+<requires>
+argon2
+hkdf
+hmac
+sha2_64
+</requires>

src/lib/pake/spake2/spake2.cpp

@@ -0,0 +1,195 @@
+/*
+* (C) 2024 Jack Lloyd
+*
+* Botan is released under the Simplified BSD License (see license.txt)
+*/
+
+#include <botan/spake2.h>
+
+#include <botan/hash.h>
+#include <botan/hex.h>
+#include <botan/pwdhash.h>
+#include <botan/internal/loadstor.h>
+#include <botan/internal/stl_util.h>
+
+namespace Botan {
+
+namespace {
+
+std::vector<uint8_t> format_spake2_ad(std::span<const uint8_t> a_identity,
+                                      std::span<const uint8_t> b_identity,
+                                      std::span<const uint8_t> context) {
+   std::vector<uint8_t> ad(a_identity.size() + b_identity.size() + context.size() + 3 * 8);
+   BufferStuffer stuffer(ad);
+
+   auto append_with_le64 = [&](std::span<const uint8_t> data) {
+      stuffer.append(store_le(static_cast<uint64_t>(data.size())));
+      stuffer.append(data);
+   };
+
+   append_with_le64(a_identity);
+   append_with_le64(b_identity);
+   append_with_le64(context);
+   return ad;
+}
+
+}  // namespace
+
+EC_Scalar SPAKE2_Parameters::hash_shared_secret(const EC_Group& group,
+                                                std::string_view shared_secret,
+                                                std::span<const uint8_t> a_identity,
+                                                std::span<const uint8_t> b_identity,
+                                                std::span<const uint8_t> context) {
+   constexpr size_t M = 128 * 1024;
+   constexpr size_t t = 3;
+   constexpr size_t p = 1;
+
+   const auto ad = format_spake2_ad(a_identity, b_identity, context);
+
+   auto pwhash_fam = PasswordHashFamily::create_or_throw("Argon2id");
+   auto pwhash = pwhash_fam->from_params(M, t, p);
+
+   secure_vector<uint8_t> w_bytes(group.get_order_bytes() + 16);
+   pwhash->hash(w_bytes, shared_secret, {}, ad, {});
+
+   return EC_Scalar::from_bytes_mod_order(group, w_bytes);
+}
+
+SPAKE2_Parameters::SPAKE2_Parameters(const EC_Group& group,
+                                     std::string_view shared_secret,
+                                     std::span<const uint8_t> a_identity,
+                                     std::span<const uint8_t> b_identity,
+                                     std::span<const uint8_t> context,
+                                     std::string_view hash,
+                                     bool per_user_params) :
+      SPAKE2_Parameters(group,
+                        SPAKE2_Parameters::hash_shared_secret(group, shared_secret, a_identity, b_identity, context),
+                        a_identity,
+                        b_identity,
+                        context,
+                        hash,
+                        per_user_params) {}
+
+namespace {
+
+std::pair<EC_AffinePoint, EC_AffinePoint> spake2_params(const EC_Group& group,
+                                                        std::string_view hash,
+                                                        std::span<const uint8_t> a_identity,
+                                                        std::span<const uint8_t> b_identity,
+                                                        std::span<const uint8_t> context,
+                                                        bool per_user_params) {
+   BOTAN_ARG_CHECK(group.has_cofactor() == false, "SPAKE2 not supported with this curve");
+
+   if(per_user_params) {
+      auto input = format_spake2_ad(a_identity, b_identity, context);
+
+      constexpr uint8_t spake2_m[] = {'S', 'P', 'A', 'K', 'E', '2', ' ', 'M'};
+      constexpr uint8_t spake2_n[] = {'S', 'P', 'A', 'K', 'E', '2', ' ', 'N'};
+
+      auto m = EC_AffinePoint::hash_to_curve_ro(group, hash, input, spake2_m);
+      auto n = EC_AffinePoint::hash_to_curve_ro(group, hash, input, spake2_n);
+
+      return std::make_pair(m, n);
+   } else {
+      const OID& group_id = group.get_curve_oid();
+
+      auto decode_pt = [&](std::string_view pt) -> EC_AffinePoint { return EC_AffinePoint(group, hex_decode(pt)); };
+
+      if(group_id == OID{1, 2, 840, 10045, 3, 1, 7}) {
+         auto m = decode_pt("02886e2f97ace46e55ba9dd7242579f2993b64e16ef3dcab95afd497333d8fa12f");
+         auto n = decode_pt("03d8bbd6c639c62937b04d997f38c3770719c629d7014d49a24b4f98baa1292b49");
+         return std::make_pair(m, n);
+      } else if(group_id == OID{1, 3, 132, 0, 34}) {
+         auto m = decode_pt(
+            "030ff0895ae5ebf6187080a82d82b42e2765e3b2f8749c7e05eba366434b363d3dc36f15314739074d2eb8613fceec2853");
+         auto n = decode_pt(
+            "02c72cf2e390853a1c1c4ad816a62fd15824f56078918f43f922ca21518f9c543bb252c5490214cf9aa3f0baab4b665c10");
+         return std::make_pair(m, n);
+      } else if(group_id == OID{1, 3, 132, 0, 35}) {
+         auto m = decode_pt(
+            "02003f06f38131b2ba2600791e82488e8d20ab889af753a41806c5db18d37d85608cfae06b82e4a72cd744c719193562a653ea1f119eef9356907edc9b56979962d7aa");
+         auto n = decode_pt(
+            "0200c7924b9ec017f3094562894336a53c50167ba8c5963876880542bc669e494b2532d76c5b53dfb349fdf69154b9e0048c58a42e8ed04cef052a3bc349d95575cd25");
+         return std::make_pair(m, n);
+      } else {
+         throw Not_Implemented("There are no defined SPAKE2 parameters for this curve");
+      }
+   }
+}
+
+}  // namespace
+
+SPAKE2_Parameters::SPAKE2_Parameters(const EC_Group& group,
+                                     const EC_Scalar& shared_secret,
+                                     std::span<const uint8_t> a_identity,
+                                     std::span<const uint8_t> b_identity,
+                                     std::span<const uint8_t> context,
+                                     std::string_view hash,
+                                     bool per_user_params) :
+      m_group(group),
+      m_params(spake2_params(m_group, hash, a_identity, b_identity, context, per_user_params)),
+      m_w(shared_secret),
+      m_hash_fn(hash),
+      m_a_identity(a_identity.begin(), a_identity.end()),
+      m_b_identity(b_identity.begin(), b_identity.end()) {}
+
+std::vector<uint8_t> SPAKE2_Context::generate_message() {
+   BOTAN_STATE_CHECK(!m_our_message.has_value());
+
+   const auto eph_key = EC_Scalar::random(m_params.group(), m_rng);
+
+   const auto& N_or_M = m_params.spake2_our_pt(m_whoami);
+   const auto& g = EC_AffinePoint::generator(m_params.group());
+   // Compute g*x + w*{M,N}
+   auto msg = EC_AffinePoint::mul_px_qy(g, eph_key, N_or_M, m_params.spake2_w(), m_rng).serialize_uncompressed();
+
+   m_our_message = std::make_pair(msg, eph_key);
+
+   return msg;
+}
+
+secure_vector<uint8_t> SPAKE2_Context::process_message(std::span<const uint8_t> peer_message) {
+   BOTAN_STATE_CHECK(m_our_message.has_value());
+
+   // Reject anything except uncompressed points
+   if(peer_message.empty() || peer_message[0] != 0x04) {
+      throw Decoding_Error("SPAKE2 key share was invalid");
+   }
+
+   // Will throw if not on the curve
+   EC_AffinePoint peer_pt(m_params.group(), peer_message);
+
+   const auto& [our_pt, eph_key] = m_our_message.value();
+   const auto& N_or_M = m_params.spake2_their_pt(m_whoami);
+   // Compute x*(pt-w*N_or_M)
+   const auto neg_xw = eph_key.negate() * m_params.spake2_w();
+   const auto K = EC_AffinePoint::mul_px_qy(peer_pt, eph_key, N_or_M, neg_xw, m_rng);
+
+   auto hash_fn = HashFunction::create_or_throw(m_params.hash_function());
+
+   auto append_to_hash_with_le64 = [&](std::span<const uint8_t> data) {
+      hash_fn->update(store_le(static_cast<uint64_t>(data.size())));
+      hash_fn->update(data);
+   };
+
+   append_to_hash_with_le64(m_params.a_identity());
+   append_to_hash_with_le64(m_params.b_identity());
+
+   // Always pA followed by pB:
+   if(m_whoami == SPAKE2_PeerId::PeerA) {
+      append_to_hash_with_le64(our_pt);
+      append_to_hash_with_le64(peer_message);
+   } else {
+      append_to_hash_with_le64(peer_message);
+      append_to_hash_with_le64(our_pt);
+   }
+
+   append_to_hash_with_le64(K.serialize_uncompressed());
+   append_to_hash_with_le64(m_params.spake2_w().serialize());
+
+   m_our_message.reset();
+
+   return hash_fn->final();
+}
+
+}  // namespace Botan