spake2p.h

Go to the documentation of this file.

/*
* (C) 2024,2025,2026 Jack Lloyd
*
* Botan is released under the Simplified BSD License (see license.txt)
*/
 
#ifndef BOTAN_PAKE_SPAKE2PLUS_H_
#define BOTAN_PAKE_SPAKE2PLUS_H_
 
#include <botan/ec_apoint.h>
#include <botan/ec_group.h>
#include <botan/ec_scalar.h>
#include <botan/secmem.h>
#include <botan/types.h>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
namespace Botan {
 
class RandomNumberGenerator;
 
}
 
/**
* SPAKE2+ (RFC 9383) password authenticated key exchange
*
* SPAKE2+ is an augmented PAKE; the two sides are asymmetric. The prover
* knows the password itself, while the verifier stores only a registration
* record derived from the password. An attacker who steals the registration
* record cannot impersonate the prover without first performing a dictionary
* attack on the record.
*
* The expected message flow is
*
*  - The prover calls ProverContext::generate_message and sends the result
*    (shareP) to the verifier.
*  - The verifier calls VerifierContext::process_message and sends the
*    result (shareV followed by confirmV) to the prover.
*  - The prover calls ProverContext::process_message, which checks the
*    verifier's key confirmation, and sends the result (confirmP) to the
*    verifier.
*  - The verifier calls VerifierContext::verify_confirmation
*
* After the final confirmation step both sides can call shared_secret to
* obtain the session key (K_shared in RFC 9383)
*
* Protocols which embed SPAKE2+ and perform the prover's key confirmation
* themselves (such as the proposed TLS PAKE extension) may instead call
* VerifierContext::skip_confirmation in place of the final step.
*/
namespace Botan::SPAKE2p {
 
/**
* SPAKE2+ (RFC 9383) System Parameters
*
* This selects the elliptic curve group, the M/N group elements, and the
* hash function; the hash also fixes the KDF (HKDF) and the MAC (HMAC)
*/
class BOTAN_PUBLIC_API(3, 13) SystemParameters final {
   public:
      /**
      * The RFC 9383 ciphersuite P256-SHA256-HKDF-HMAC-SHA256
      */
      static SystemParameters rfc9383_p256_sha256();
 
      /**
      * The RFC 9383 ciphersuite P256-SHA512-HKDF-HMAC-SHA512
      */
      static SystemParameters rfc9383_p256_sha512();
 
      /**
      * The RFC 9383 ciphersuite P384-SHA256-HKDF-HMAC-SHA256
      */
      static SystemParameters rfc9383_p384_sha256();
 
      /**
      * The RFC 9383 ciphersuite P384-SHA512-HKDF-HMAC-SHA512
      */
      static SystemParameters rfc9383_p384_sha512();
 
      /**
      * The RFC 9383 ciphersuite P521-SHA512-HKDF-HMAC-SHA512
      */
      static SystemParameters rfc9383_p521_sha512();
 
      /**
      * SPAKE2+ custom system parameters for an arbitrary group
      *
      * The M/N values will be derived from the seed using hash2curve;
      * note that not all groups support hash2curve.
      *
      * RFC 9383 Section 3.2: "Applications MAY use different M and N
      * values, provided they are computed, e.g., using different input
      * seeds to the algorithm in Appendix B, as random elements for
      * which the discrete log is unknown."
      *
      * If the seed includes the identities of the participants, this
      * additionally makes the scheme "quantum annoying", in that an attacker
      * with a discrete logarithm oracle must compute a new discrete log for
      * each (user, verifier) pair they wish to attack.
      *
      * @param group the elliptic curve group to use
      * @param seed the seed bytes used to derive M and N
      * @param hash_fn the hash function to use (eg "SHA-256")
      */
      static SystemParameters custom(const EC_Group& group, std::span<const uint8_t> seed, std::string_view hash_fn);
 
      /**
      * Return the elliptic curve group
      */
      const EC_Group& group() const { return m_group; }
 
      /**
      * Return the SPAKE2+ M group element
      */
      const EC_AffinePoint& spake2p_m() const { return m_spake2p_m; }
 
      /**
      * Return the SPAKE2+ N group element
      */
      const EC_AffinePoint& spake2p_n() const { return m_spake2p_n; }
 
      /**
      * Return the name of the hash function
      */
      const std::string& hash_function() const { return m_hash_fn; }
 
      /**
      * Return the size in bytes of a key share (shareP or shareV)
      */
      size_t share_size() const;
 
      /**
      * Return the size in bytes of a key confirmation message (confirmP or confirmV)
      */
      size_t confirmation_size() const;
 
   private:
      SystemParameters(EC_Group group, EC_AffinePoint m, EC_AffinePoint n, std::string_view hash_fn);
 
      EC_Group m_group;
      EC_AffinePoint m_spake2p_m;
      EC_AffinePoint m_spake2p_n;
      std::string m_hash_fn;
};
 
class ProverSecret;
 
/**
* SPAKE2+ Registration Record
*
* This is the information (w0 and L in RFC 9383) which the verifier
* stores in order to authenticate the prover.
*/
class BOTAN_PUBLIC_API(3, 13) RegistrationRecord final {
   public:
      /**
      * Perform password registration, returning the registration record
      *
      * This derives the record from the password using Argon2id; see
      * ProverSecret::from_password for the details. The same password,
      * identities, and salt must later be used to create the prover's secret.
      *
      * The identities and salt may be empty.
      */
      static RegistrationRecord 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,
                                              RandomNumberGenerator& rng);
 
      /**
      * Deserialize a RegistrationRecord previously serialized by serialize
      */
      static RegistrationRecord deserialize(const SystemParameters& params, std::span<const uint8_t> record);
 
      /**
      * Serialize the registration record
      *
      * @warning the return value is the unencrypted registration record, which
      * is a sensitive value allowing password guessing attacks. Encrypt it for
      * persistent storage if possible.
      */
      secure_vector<uint8_t> serialize() const;
 
   private:
      friend class ProverSecret;
      friend class VerifierContext;
 
      RegistrationRecord(EC_Scalar w0, EC_AffinePoint l) : m_w0(std::move(w0)), m_l(std::move(l)) {}
 
      EC_Scalar m_w0;
      EC_AffinePoint m_l;
};
 
/**
* 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.
*/
class BOTAN_PUBLIC_API(3, 13) ProverSecret final {
   public:
      /**
      * 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.
      */
      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);
 
      /**
      * Create a prover secret from already derived scalars
      *
      * @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.
      */
      static ProverSecret from_prehashed(EC_Scalar w0, EC_Scalar w1);
 
      /**
      * Deserialize a ProverSecret previously serialized by serialize
      */
      static ProverSecret deserialize(const SystemParameters& params, std::span<const uint8_t> secret);
 
      /**
      * Serialize the prover secret
      *
      * @warning the return value is password equivalent; encrypt it for
      * persistent storage if possible.
      */
      secure_vector<uint8_t> serialize() 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.
      */
      RegistrationRecord registration_record(RandomNumberGenerator& rng) const;
 
   private:
      friend class ProverContext;
 
      ProverSecret(EC_Scalar w0, EC_Scalar w1) : m_w0(std::move(w0)), m_w1(std::move(w1)) {}
 
      EC_Scalar m_w0;
      EC_Scalar m_w1;
};
 
/**
* 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.
*/
class BOTAN_PUBLIC_API(3, 13) ProverContext final {
   public:
      /**
      * 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.
      */
      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 = {});
 
      /**
      * Generate the prover's key share (shareP), which is sent to the verifier.
      *
      * This can be called only once.
      */
      std::vector<uint8_t> generate_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).
      */
      std::vector<uint8_t> process_message(std::span<const uint8_t> peer_message, RandomNumberGenerator& rng);
 
      /**
      * Return the shared secret (K_shared)
      *
      * This may be called only after process_message has succeeded.
      */
      secure_vector<uint8_t> shared_secret() const;
 
      /**
      * Return the system parameters
      */
      const SystemParameters& parameters() const { return m_params; }
 
   private:
      enum class State : uint8_t { Initial, ShareGenerated, Complete, Failed };
 
      SystemParameters m_params;
      ProverSecret m_secret;
      std::vector<uint8_t> m_prover_id;
      std::vector<uint8_t> m_verifier_id;
      std::vector<uint8_t> m_context;
      std::optional<std::pair<std::vector<uint8_t>, EC_Scalar>> m_our_message;
      secure_vector<uint8_t> m_shared_secret;
      State m_state = State::Initial;
};
 
/**
* SPAKE2+ (RFC 9383) Verifier
*
* The verifier does not know the password itself; it stores only the
* registration record.
*/
class BOTAN_PUBLIC_API(3, 13) VerifierContext final {
   public:
      /**
      * 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.
      */
      VerifierContext(const SystemParameters& params,
                      const RegistrationRecord& record,
                      std::span<const uint8_t> prover_id,
                      std::span<const uint8_t> verifier_id,
                      std::span<const uint8_t> context = {});
 
      /**
      * Consume the prover's key share (shareP) and return the verifier's
      * response (shareV followed by confirmV), which is sent to the prover.
      *
      * This can be called only once. Throws Decoding_Error if the key
      * share is malformed.
      */
      std::vector<uint8_t> process_message(std::span<const uint8_t> peer_message, RandomNumberGenerator& rng);
 
      /**
      * Check the prover's key confirmation (confirmP)
      *
      * Throws Invalid_Authentication_Tag if the confirmation is wrong,
      * meaning the prover does not know the password.
      */
      void verify_confirmation(std::span<const uint8_t> confirmation);
 
      /**
      * Skip checking the prover's key confirmation (confirmP)
      *
      * This can be called after process_message, in place of
      * verify_confirmation, to allow extracting the shared secret without
      * having checked the prover's key confirmation.
      *
      * @warning After calling this, nothing is known about the peer; only
      * a prover which knows the password can compute the same shared
      * secret, but no evidence of this has been received. It is intended
      * solely for protocols which embed SPAKE2+ and perform the prover's
      * key confirmation themselves, for example the proposed TLS PAKE
      * extension, where the TLS handshake takes the place of confirmP.
      * Anywhere else, use verify_confirmation.
      */
      void skip_confirmation();
 
      /**
      * Return the shared secret (K_shared)
      *
      * This may be called only after verify_confirmation has succeeded,
      * or after skip_confirmation.
      *
      * RFC 9383 Section 3.3: "The Verifier MUST NOT send application data
      * to the Prover until it has received and verified the confirmation
      * message."
      */
      secure_vector<uint8_t> shared_secret() const;
 
      /**
      * Return the system parameters
      */
      const SystemParameters& parameters() const { return m_params; }
 
   private:
      enum class State : uint8_t { Initial, Responded, Complete, Failed };
 
      SystemParameters m_params;
      RegistrationRecord m_record;
      std::vector<uint8_t> m_prover_id;
      std::vector<uint8_t> m_verifier_id;
      std::vector<uint8_t> m_context;
      std::vector<uint8_t> m_expected_confirmation;
      secure_vector<uint8_t> m_shared_secret;
      State m_state = State::Initial;
};
 
}  // namespace Botan::SPAKE2p
 
#endif