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

#include <spake2p.h>

Public Member Functions

RegistrationRecord registration_record (RandomNumberGenerator &rng) const
secure_vector< uint8_t > serialize () const

Static Public Member Functions

static ProverSecret deserialize (const SystemParameters &params, std::span< const uint8_t > secret)
static ProverSecret from_password (const SystemParameters &params, std::string_view password, std::span< const uint8_t > prover_id, std::span< const uint8_t > verifier_id, std::span< const uint8_t > salt)
static ProverSecret from_prehashed (EC_Scalar w0, EC_Scalar w1)

Friends

class ProverContext

Detailed Description

SPAKE2+ Prover Secret

This is the information (w0 and w1 in RFC 9383) which the prover derives from the password in order to authenticate itself.

Definition at line 207 of file spake2p.h.

Member Function Documentation

◆ deserialize()

ProverSecret Botan::SPAKE2p::ProverSecret::deserialize ( const SystemParameters & params,
std::span< const uint8_t > secret )
static

Deserialize a ProverSecret previously serialized by serialize

Definition at line 301 of file spake2p.cpp.

301 {
302 if(auto w0_w1 = EC_Scalar::deserialize_pair(params.group(), secret)) {
303 return ProverSecret(std::move(w0_w1->first), std::move(w0_w1->second));
304 } else {
305 throw Decoding_Error("Invalid SPAKE2+ prover secret");
306 }
307}
static std::optional< std::pair< EC_Scalar, EC_Scalar > > deserialize_pair(const EC_Group &group, std::span< const uint8_t > bytes)

References Botan::EC_Scalar::deserialize_pair(), and Botan::SPAKE2p::SystemParameters::group().

Referenced by botan_spake2p_prover_init(), and botan_spake2p_registration_record().

◆ from_password()

ProverSecret Botan::SPAKE2p::ProverSecret::from_password ( const SystemParameters & params,
std::string_view password,
std::span< const uint8_t > prover_id,
std::span< const uint8_t > verifier_id,
std::span< const uint8_t > salt )
static

Derive the prover secret from a password

The derivation uses Argon2id with the memory-constrained parameters from RFC 9106, namely m=64 MiB, t=3, p=4. Following RFC 9383, the Argon2id passphrase input is the concatenation

len(pw) || pw || len(idProver) || idProver || len(idVerifier) || idVerifier

with each length an 8-byte little-endian count of bytes, and the salt is provided to Argon2id directly. The Argon2id output is split in two halves, each of which is reduced modulo the group order.

The identities and salt may be empty; if a salt is available it should be used, as this prevents precomputed dictionary attacks.

Definition at line 288 of file spake2p.cpp.

292 {
293 auto [w0, w1] = derive_w0_w1(params, password, prover_id, verifier_id, salt);
294 return ProverSecret(std::move(w0), std::move(w1));
295}

Referenced by botan_spake2p_derive_secret(), and Botan::SPAKE2p::RegistrationRecord::from_password().

◆ from_prehashed()

ProverSecret Botan::SPAKE2p::ProverSecret::from_prehashed ( EC_Scalar w0,
EC_Scalar w1 )
static

Create a prover secret from already derived scalars

Throws Invalid_Argument if either scalar is zero.

Warning
This interface is potentially unsafe, depending upon how the scalars are derived from the password. They must be uniformly random, and preferably computed in a way such that testing password guesses is expensive for an attacker. It exists to support testing, as well as applications which require using a different password hashing scheme than the default one implemented by from_password.

Definition at line 297 of file spake2p.cpp.

297 {
298 return ProverSecret(std::move(w0), std::move(w1));
299}

◆ registration_record()

RegistrationRecord Botan::SPAKE2p::ProverSecret::registration_record ( RandomNumberGenerator & rng) const

Compute the registration record (w0 and L=w1*P) for this secret

This would typically be done once, when the password is first registered with the verifier.

Definition at line 313 of file spake2p.cpp.

313 {
314 const auto scope = CT::scoped_poison(m_w1);
315 // RFC 9383 Section 3.2: "the registration record L=w1*P"
316 return RegistrationRecord(m_w0, CT::driveby_unpoison(EC_AffinePoint::g_mul(m_w1, rng)));
317}
static EC_AffinePoint g_mul(const EC_Scalar &scalar, RandomNumberGenerator &rng)
Multiply by the group generator returning a complete point.
constexpr decltype(auto) driveby_unpoison(T &&v)
Definition ct_utils.h:243
constexpr auto scoped_poison(const Ts &... xs)
Definition ct_utils.h:222

References Botan::CT::driveby_unpoison(), Botan::EC_AffinePoint::g_mul(), and Botan::CT::scoped_poison().

Referenced by Botan::SPAKE2p::RegistrationRecord::from_password().

◆ serialize()

secure_vector< uint8_t > Botan::SPAKE2p::ProverSecret::serialize ( ) const

Serialize the prover secret

Warning
the return value is password equivalent; encrypt it for persistent storage if possible.

Definition at line 309 of file spake2p.cpp.

309 {
311}
static T serialize_pair(const EC_Scalar &r, const EC_Scalar &s)
Definition ec_scalar.h:161

References Botan::EC_Scalar::serialize_pair().

◆ ProverContext

friend class ProverContext
friend

Definition at line 267 of file spake2p.h.

References ProverContext.

Referenced by ProverContext.


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