Skip to content

Commit

Permalink
Add SPAKE2 password authenticated key exchange (RFC 9382)
Browse files Browse the repository at this point in the history
  • Loading branch information
randombit committed Nov 18, 2024
1 parent 162a389 commit af3b206
Show file tree
Hide file tree
Showing 8 changed files with 682 additions and 0 deletions.
1 change: 1 addition & 0 deletions doc/api_ref/contents.rst
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ API Reference
keywrap
passhash
cryptobox
spake2
srp
psk_db
filters
Expand Down
80 changes: 80 additions & 0 deletions doc/api_ref/spake2.rst
Original file line number Diff line number Diff line change
@@ -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)
19 changes: 19 additions & 0 deletions src/lib/pake/spake2/info.txt
Original file line number Diff line number Diff line change
@@ -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>
195 changes: 195 additions & 0 deletions src/lib/pake/spake2/spake2.cpp
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit af3b206

Please sign in to comment.