SPAKE2+ Password Authenticated Key Exchange ============================================= .. versionadded:: 3.13.0 An implementation of the SPAKE2+ password authenticated key exchange, compatible with RFC 9383, is included. SPAKE2+ allows two peers who share a (possibly low entropy) secret such as a password to agree on a strong shared secret key. An attacker who observes or modifies the exchange learns nothing about the password (beyond excluding a single guess per protocol execution) or the session key. SPAKE2+ is an *augmented* PAKE, meaning the two sides are asymmetric. The *prover* (typically a client) knows the password itself, while the *verifier* (typically a server) stores only a *registration record* derived from the password. An attacker who steals the registration record cannot impersonate the prover without first performing a successful dictionary attack against the record. The protocol consists of two phases: * *Registration* (performed once, over some trusted channel): the prover derives its secret values from the password, and provides the resulting registration record to the verifier. * *Online authentication* (performed per session): the two sides exchange key shares and key confirmation messages, resulting in a mutually authenticated shared secret. The online message flow is:: Prover Verifier ProverContext::generate_message --- shareP --> VerifierContext::process_message <-- shareV || confirmV --- ProverContext::process_message --- confirmP --> VerifierContext::verify_confirmation After the final step both sides call ``shared_secret`` to obtain the session key (``K_shared`` in RFC 9383). Some protocols which embed SPAKE2+ perform the prover's key confirmation themselves rather than exchanging ``confirmP``. For example in the proposed PAKE extension for TLS 1.3 (draft-bmw-tls-pake13), the server acts as the verifier, feeds the shared secret into the TLS key schedule immediately after processing the prover's key share, and the TLS handshake takes the place of ``confirmP``. To support such protocols, the verifier may call ``skip_confirmation`` in place of ``verify_confirmation``; see below. System Parameters ------------------- .. cpp:class:: SPAKE2p::SystemParameters Specifies the ciphersuite in use, namely the elliptic curve group, the SPAKE2+ ``M``/``N`` group elements, and the hash function. SPAKE2+ parameters include a KDF and an authentication code. The KDF is always HKDF using the specified hash, and the MAC is always HMAC using the specified hash. In particular the CMAC-based SPAKE2+ suites described in RFC 9383 Table 1 are not supported. Static factory functions ``rfc9383_p256_sha256``, ``rfc9383_p256_sha512``, ``rfc9383_p384_sha256``, ``rfc9383_p384_sha512``, and ``rfc9383_p521_sha512`` return the standard ciphersuites from RFC 9383. .. cpp:function:: static SystemParameters custom(const EC_Group& group, \ std::span seed, \ std::string_view hash_fn) Creates custom system parameters for an arbitrary group, deriving the ``M``/``N`` elements from the seed using hash to curve (which not all groups support). Both peers must use the same seed. If the seed includes the identities of the participants, this additionally makes the scheme "quantum annoying": an attacker with a discrete logarithm oracle must compute a new discrete logarithm for each (prover, verifier) pair they wish to attack, rather than being able to attack any user after computing the discrete logarithms of the fixed ``M``/``N`` elements once. Registration -------------- .. cpp:class:: SPAKE2p::ProverSecret The secret values (``w0`` and ``w1`` in RFC 9383) which the prover derives from the password. .. cpp:function:: static ProverSecret from_password(const SystemParameters& params, \ std::string_view password, \ std::span prover_id, \ std::span verifier_id, \ std::span salt) Derives the prover secret from a password using Argon2id, with the memory-constrained parameters recommended in RFC 9106 (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``, where each length is an 8-byte little-endian count of bytes; the salt is provided to Argon2id directly. The output is split into two halves, each of which is reduced modulo the group order. The identities and the salt may be empty; if a salt is available it should be used, since it prevents precomputed dictionary attacks. .. cpp:function:: static ProverSecret from_prehashed(EC_Scalar w0, EC_Scalar w1) Creates a prover secret from already derived scalars, for applications which require a password hashing scheme other than the default one. The scalars must be derived from the password in a way that produces uniformly random values modulo the group order; see RFC 9383 section 3.2 for the requirements. .. cpp:function:: RegistrationRecord registration_record(RandomNumberGenerator& rng) const Computes the registration record (``w0`` and ``L = w1*P``) which is provided to the verifier during registration. .. cpp:function:: static ProverSecret deserialize(const SystemParameters& params, \ std::span secret) .. cpp:function:: secure_vector serialize() const Serialization, if the prover wishes to store the derived secret rather than rederiving it from the password each time. The serialized secret is password equivalent, so it should be encrypted if stored persistently. .. cpp:class:: SPAKE2p::RegistrationRecord The information (``w0`` and ``L`` in RFC 9383) which the verifier stores in order to later authenticate the prover. .. cpp:function:: static RegistrationRecord from_password(const SystemParameters& params, \ std::string_view password, \ std::span prover_id, \ std::span verifier_id, \ std::span salt, \ RandomNumberGenerator& rng) Performs password registration in a single step, equivalent to ``ProverSecret::from_password`` followed by ``registration_record``. .. cpp:function:: static RegistrationRecord deserialize(const SystemParameters& params, \ std::span record) .. cpp:function:: secure_vector serialize() const Serialization, for storage by the verifier. While the record does not allow direct impersonation of the prover, it does allow offline password guessing attacks, so it should be encrypted if possible. Online Authentication ----------------------- .. cpp:class:: SPAKE2p::ProverContext .. cpp:function:: ProverContext(const SystemParameters& params, \ const ProverSecret& secret, \ std::span prover_id, \ std::span verifier_id, \ std::span context = {}) Prepares an execution of the protocol. The identities and the context must be agreed upon by both peers, and the identities must match the values used during registration. Even if there is no natural identity available, using fixed labels such as "client" and "server" is preferable to leaving the identities empty. The context should identify the application and protocol version; it may be empty. .. cpp:function:: std::vector generate_message(RandomNumberGenerator& rng) Returns the prover's key share (``shareP``), which is sent to the verifier. Can be called only once. .. cpp:function:: std::vector process_message(std::span peer_message, \ RandomNumberGenerator& rng) Consumes the verifier's response (``shareV || confirmV``) and returns the prover's key confirmation (``confirmP``), which is sent to the verifier. Throws ``Decoding_Error`` if the message is malformed, or ``Invalid_Authentication_Tag`` if the key confirmation is wrong (typically meaning the passwords do not match). .. cpp:function:: secure_vector shared_secret() const Returns the shared secret. May be called only after ``process_message`` has succeeded. .. cpp:class:: SPAKE2p::VerifierContext .. cpp:function:: VerifierContext(const SystemParameters& params, \ const RegistrationRecord& record, \ std::span prover_id, \ std::span verifier_id, \ std::span context = {}) Prepares an execution of the protocol; see ``ProverContext`` above for the requirements on the identities and context. .. cpp:function:: std::vector process_message(std::span peer_message, \ RandomNumberGenerator& rng) Consumes the prover's key share (``shareP``) and returns the verifier's response (``shareV || confirmV``), which is sent to the prover. Can be called only once. Throws ``Decoding_Error`` if the key share is malformed. .. cpp:function:: void verify_confirmation(std::span confirmation) Checks the prover's key confirmation (``confirmP``). Throws ``Invalid_Authentication_Tag`` if the confirmation is wrong, meaning the prover does not know the password. .. cpp:function:: void skip_confirmation() 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, such as the proposed PAKE extension for TLS 1.3, where the TLS handshake takes the place of ``confirmP``. Anywhere else, use ``verify_confirmation``. .. cpp:function:: secure_vector shared_secret() const Returns the shared secret. May be called only after ``verify_confirmation`` has succeeded, or after ``skip_confirmation``. Code Example: SPAKE2+ PAKE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The example below demonstrates using SPAKE2+ to perform a password authenticated key exchange. .. literalinclude:: /../src/examples/spake2p.cpp :language: cpp