Botan::SPAKE2p::ProverContext Class Reference

#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 279 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 313 of file spake2p.cpp.

                                                             :
      m_params(params),
      m_secret(secret),
      m_prover_id(prover_id.begin(), prover_id.end()),
      m_verifier_id(verifier_id.begin(), verifier_id.end()),
      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 324 of file spake2p.cpp.

                                                                             {
   BOTAN_STATE_CHECK(m_state == State::Initial);
 
   const auto x = EC_Scalar::random(m_params.group(), rng);
   const auto g = EC_AffinePoint::generator(m_params.group());
 
   // RFC 9383 Section 3.3: X = x*P + w0*M
   if(auto share_p = EC_AffinePoint::mul_px_qy(g, x, m_params.spake2p_m(), m_secret.m_w0, rng)) {
      m_our_message = std::make_pair(share_p->serialize_uncompressed(), x);
      m_state = State::ShareGenerated;
      return m_our_message->first;
   } else {
      throw Internal_Error("Computed the identity element during SPAKE2+ key exchange");
   }
}

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

parameters()

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

inline

Return the system parameters

Definition at line 322 of file spake2p.h.

{ 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).

Definition at line 340 of file spake2p.cpp.

                                                                                                                 {
   BOTAN_STATE_CHECK(m_state == State::ShareGenerated);
 
   const size_t share_size = m_params.share_size();
   const size_t confirm_size = m_params.confirmation_size();
 
   if(peer_message.size() != share_size + confirm_size) {
      throw Decoding_Error("Invalid length for SPAKE2+ verifier message");
   }
 
   const auto share_v = peer_message.first(share_size);
   const auto confirm_v = peer_message.last(confirm_size);
 
   const auto y = EC_AffinePoint::deserialize_uncompressed(m_params.group(), share_v);
   if(!y) {
      throw Decoding_Error("Invalid SPAKE2+ key share");
   }
 
   const auto& w0 = m_secret.m_w0;
   const auto& w1 = m_secret.m_w1;
   const auto& n = m_params.spake2p_n();
   const auto& x = m_our_message->second;
 
   // RFC 9383 Section 3.3: Z = h*x*(Y - w0*N), V = h*w1*(Y - w0*N)
   const auto z = EC_AffinePoint::mul_px_qy(*y, x, n, (x * w0).negate(), rng);
   const auto v = EC_AffinePoint::mul_px_qy(*y, w1, n, (w1 * w0).negate(), rng);
 
   if(!z || !v) {
      throw Decoding_Error("Invalid SPAKE2+ key share");
   }
 
   auto keys =
      spake2p_key_schedule(m_params, m_context, m_prover_id, m_verifier_id, m_our_message->first, share_v, *z, *v, w0);
 
   if(!constant_time_compare(keys.confirm_v, confirm_v)) {
      m_our_message.reset();
      m_state = State::Failed;
      throw Invalid_Authentication_Tag("SPAKE2+ key confirmation failed");
   }
 
   m_shared_secret = std::move(keys.shared_key);
   m_our_message.reset();
   m_state = State::Complete;
 
   return keys.confirm_p;
}

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

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 387 of file spake2p.cpp.

                                                          {
   BOTAN_STATE_CHECK(m_state == State::Complete);
   return m_shared_secret;
}

References BOTAN_STATE_CHECK.

---

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

• src/lib/pake/spake2p/spake2p.h
• src/lib/pake/spake2p/spake2p.cpp