Botan 3.14.1
Crypto and TLS for C&
Botan::SPAKE2p::ProverContext Class Referencefinal

#include <spake2p.h>

Public Member Functions

std::vector< uint8_t > generate_message (RandomNumberGenerator &rng)
const SystemParameters & parameters () const
std::vector< uint8_t > process_message (std::span< const uint8_t > peer_message, RandomNumberGenerator &rng)
 ProverContext (const SystemParameters &params, const ProverSecret &secret, std::span< const uint8_t > prover_id, std::span< const uint8_t > verifier_id, std::span< const uint8_t > context={})
secure_vector< uint8_t > shared_secret () const

Detailed Description

SPAKE2+ (RFC 9383) Prover

The prover knows the password secret (w0 and w1) and authenticates itself to a verifier which knows the matching registration record.

Definition at line 281 of file spake2p.h.

Constructor & Destructor Documentation

◆ ProverContext()

Botan::SPAKE2p::ProverContext::ProverContext ( const SystemParameters & params,
const ProverSecret & secret,
std::span< const uint8_t > prover_id,
std::span< const uint8_t > verifier_id,
std::span< const uint8_t > context = {} )

Set up for an execution of the protocol

The identities and context must be agreed upon by both parties; the identities must additionally match the values used during password registration. Both the identities and the context may be empty.

Definition at line 319 of file spake2p.cpp.

323 :
324 m_params(params),
325 m_secret(secret),
326 m_prover_id(prover_id.begin(), prover_id.end()),
327 m_verifier_id(verifier_id.begin(), verifier_id.end()),
328 m_context(context.begin(), context.end()) {}

Member Function Documentation

◆ generate_message()

std::vector< uint8_t > Botan::SPAKE2p::ProverContext::generate_message ( RandomNumberGenerator & rng)

Generate the prover's key share (shareP), which is sent to the verifier.

This can be called only once.

Definition at line 330 of file spake2p.cpp.

330 {
331 BOTAN_STATE_CHECK(m_state == State::Initial);
332
333 const auto x = EC_Scalar::random(m_params.group(), rng);
334 const auto g = EC_AffinePoint::generator(m_params.group());
335
336 const auto scope = CT::scoped_poison(x, m_secret.m_w0);
337
338 // RFC 9383 Section 3.3: X = x*P + w0*M
339 if(auto share_p = EC_AffinePoint::mul_px_qy(g, x, m_params.spake2p_m(), m_secret.m_w0, rng)) {
340 CT::unpoison(*share_p);
341 m_our_message = std::make_pair(share_p->serialize_uncompressed(), x);
342 m_state = State::ShareGenerated;
343 return m_our_message->first;
344 } else {
345 throw Internal_Error("Computed the identity element during SPAKE2+ key exchange");
346 }
347}
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
static std::optional< EC_AffinePoint > mul_px_qy(const EC_AffinePoint &p, const EC_Scalar &x, const EC_AffinePoint &q, const EC_Scalar &y, RandomNumberGenerator &rng)
static EC_AffinePoint generator(const EC_Group &group)
Return the standard group generator.
Definition ec_apoint.cpp:84
static EC_Scalar random(const EC_Group &group, RandomNumberGenerator &rng)
Definition ec_scalar.cpp:76
constexpr auto scoped_poison(const Ts &... xs)
Definition ct_utils.h:222
constexpr void unpoison(const T *p, size_t n)
Definition ct_utils.h:67

References BOTAN_STATE_CHECK, Botan::EC_AffinePoint::generator(), Botan::EC_AffinePoint::mul_px_qy(), Botan::EC_Scalar::random(), Botan::CT::scoped_poison(), and Botan::CT::unpoison().

◆ parameters()

const SystemParameters & Botan::SPAKE2p::ProverContext::parameters ( ) const
inline

Return the system parameters

Definition at line 325 of file spake2p.h.

325{ return m_params; }

◆ process_message()

std::vector< uint8_t > Botan::SPAKE2p::ProverContext::process_message ( std::span< const uint8_t > peer_message,
RandomNumberGenerator & rng )

Consume the message from the verifier (shareV followed by confirmV) and return the prover's key confirmation (confirmP), which is sent to the verifier.

Throws Decoding_Error if the message is malformed, and Invalid_Authentication_Tag if the verifier's key confirmation is wrong (typically due to a password mismatch). After any failure the context cannot be used further.

Definition at line 349 of file spake2p.cpp.

349 {
350 BOTAN_STATE_CHECK(m_state == State::ShareGenerated && m_our_message.has_value());
351
352 // Any failure from here on is terminal, and destroys our ephemeral scalar x
353 m_state = State::Failed;
354 const auto our_message = std::exchange(m_our_message, std::nullopt);
355 const auto& share_p = our_message->first;
356 const auto& x = our_message->second;
357
358 const size_t share_size = m_params.share_size();
359 const size_t confirm_size = m_params.confirmation_size();
360
361 if(peer_message.size() != share_size + confirm_size) {
362 throw Decoding_Error("Invalid length for SPAKE2+ verifier message");
363 }
364
365 const auto share_v = peer_message.first(share_size);
366 const auto confirm_v = peer_message.last(confirm_size);
367
368 const auto y = EC_AffinePoint::deserialize_uncompressed(m_params.group(), share_v);
369 if(!y) {
370 throw Decoding_Error("Invalid SPAKE2+ key share");
371 }
372
373 const auto& w0 = m_secret.m_w0;
374 const auto& w1 = m_secret.m_w1;
375 const auto& n = m_params.spake2p_n();
376
377 const auto scope = CT::scoped_poison(x, w0, w1);
378
379 // RFC 9383 Section 3.3: Z = h*x*(Y - w0*N), V = h*w1*(Y - w0*N)
380 const auto z = EC_AffinePoint::mul_px_qy(*y, x, n, (x * w0).negate(), rng);
381 const auto v = EC_AffinePoint::mul_px_qy(*y, w1, n, (w1 * w0).negate(), rng);
382
383 if(!z || !v) {
384 throw Decoding_Error("Invalid SPAKE2+ key share");
385 }
386
387 auto keys = spake2p_key_schedule(m_params, m_context, m_prover_id, m_verifier_id, share_p, share_v, *z, *v, w0);
388 // Any further secret handling of the output is up to the caller
389 CT::unpoison_all(keys.shared_key, keys.confirm_p, keys.confirm_v);
390
391 if(!constant_time_compare(keys.confirm_v, confirm_v)) {
392 throw Invalid_Authentication_Tag("SPAKE2+ key confirmation failed");
393 }
394
395 m_shared_secret = std::move(keys.shared_key);
396 m_state = State::Complete;
397
398 return keys.confirm_p;
399}
static std::optional< EC_AffinePoint > deserialize_uncompressed(const EC_Group &group, std::span< const uint8_t > bytes)
constexpr void unpoison_all(const Ts &... ts)
Definition ct_utils.h:207
bool constant_time_compare(std::span< const uint8_t > x, std::span< const uint8_t > y)
Definition mem_ops.cpp:17

References BOTAN_STATE_CHECK, Botan::constant_time_compare(), Botan::EC_AffinePoint::deserialize_uncompressed(), Botan::EC_AffinePoint::mul_px_qy(), Botan::CT::scoped_poison(), and Botan::CT::unpoison_all().

◆ shared_secret()

secure_vector< uint8_t > Botan::SPAKE2p::ProverContext::shared_secret ( ) const

Return the shared secret (K_shared)

This may be called only after process_message has succeeded.

Definition at line 401 of file spake2p.cpp.

401 {
402 BOTAN_STATE_CHECK(m_state == State::Complete);
403 return m_shared_secret;
404}

References BOTAN_STATE_CHECK.


The documentation for this class was generated from the following files: