Add SPAKE2+ password authenticated key exchange (RFC 9383)

Author: randombit

doc/api_ref/contents.rst

@@ -24,6 +24,7 @@ API Reference
    keywrap
    passhash
    cryptobox
+   spake2p
    srp
    psk_db
    filters

doc/api_ref/ffi.rst

@@ -2435,6 +2435,175 @@ All available value types of the generic X.509 object getters are:
    The URLs of the issuing CA certificate of a certificate as a character array.
    There might be more than one such URL defined in a certificate.
 
+SPAKE2+ Password Authenticated Key Exchange
+--------------------------------------------
+
+.. versionadded:: 3.13.0
+
+An implementation of the SPAKE2+ password authenticated key exchange
+(RFC 9383). The *prover* knows the password itself, while the *verifier*
+stores only a registration record derived from the password. See
+:doc:`spake2p` for a description of the protocol and the expected
+message flow.
+
+The identity, salt, and context parameters of these functions may be null,
+if the corresponding length is zero. Since the lengths of the outputs vary
+with the system parameters, all outputs are produced using view callbacks.
+
+.. cpp:type:: opaque* botan_spake2p_params_t
+
+   An opaque data type for SPAKE2+ system parameters, which select the
+   elliptic curve group, the SPAKE2+ M/N group elements, and the hash
+   function. Objects created from the system parameters hold their own
+   copy, so the parameters may be destroyed at any time.
+
+.. cpp:function:: int botan_spake2p_params_init(botan_spake2p_params_t* params, const char* ciphersuite)
+
+   Create system parameters from an RFC 9383 ciphersuite name, one of
+   "P256-SHA256", "P256-SHA512", "P384-SHA256", "P384-SHA512", or
+   "P521-SHA512", all using HMAC key confirmation.
+
+.. cpp:function:: int botan_spake2p_params_init_custom(botan_spake2p_params_t* params, \
+                  botan_ec_group_t group, const uint8_t seed[], size_t seed_len, \
+                  const char* hash_fn)
+
+   Create custom system parameters for an arbitrary group, deriving the
+   M/N group elements from the seed using hash to curve; returns
+   ``BOTAN_FFI_ERROR_NOT_IMPLEMENTED`` if the group does not support hash
+   to curve. Both peers must use the same group, seed, and hash.
+
+.. cpp:function:: int botan_spake2p_params_destroy(botan_spake2p_params_t params)
+
+   Destroy an object.
+
+.. cpp:function:: int botan_spake2p_params_share_size(botan_spake2p_params_t params, size_t* share_size)
+
+   Return the size in bytes of a key share (shareP or shareV).
+
+.. cpp:function:: int botan_spake2p_params_confirmation_size(botan_spake2p_params_t params, size_t* confirmation_size)
+
+   Return the size in bytes of a key confirmation message (confirmP or confirmV).
+
+.. cpp:function:: int botan_spake2p_derive_secret(botan_spake2p_params_t params, \
+                  const char* password, \
+                  const uint8_t prover_id[], size_t prover_id_len, \
+                  const uint8_t verifier_id[], size_t verifier_id_len, \
+                  const uint8_t salt[], size_t salt_len, \
+                  botan_view_ctx ctx, botan_view_bin_fn view)
+
+   Derive a prover secret (w0 and w1) from a password, using Argon2id.
+   The view callback is invoked with the serialized prover secret, which
+   is password equivalent and must be protected accordingly. It is used
+   with ``botan_spake2p_registration_record`` and
+   ``botan_spake2p_prover_init``.
+
+.. cpp:function:: int botan_spake2p_registration_record(botan_spake2p_params_t params, \
+                  botan_rng_t rng, const uint8_t secret[], size_t secret_len, \
+                  botan_view_ctx ctx, botan_view_bin_fn view)
+
+   Compute a registration record (w0 and L) from a serialized prover
+   secret. The record is provided to the verifier during registration.
+   While it does not allow directly impersonating the prover, it does
+   allow offline password guessing attacks, so it should be protected.
+
+.. cpp:type:: opaque* botan_spake2p_prover_t
+
+   An opaque data type for a SPAKE2+ prover.
+
+.. cpp:function:: int botan_spake2p_prover_init(botan_spake2p_prover_t* prover, \
+                  botan_spake2p_params_t params, \
+                  const uint8_t secret[], size_t secret_len, \
+                  const uint8_t prover_id[], size_t prover_id_len, \
+                  const uint8_t verifier_id[], size_t verifier_id_len, \
+                  const uint8_t context[], size_t context_len)
+
+   Initialize a prover from a serialized prover secret. The identities
+   and context must be agreed upon by both parties; the identities must
+   additionally match the values used when deriving the prover secret.
+
+.. cpp:function:: int botan_spake2p_prover_destroy(botan_spake2p_prover_t prover)
+
+   Destroy an object.
+
+.. cpp:function:: int botan_spake2p_prover_generate_message(botan_spake2p_prover_t prover, \
+                  botan_rng_t rng, botan_view_ctx ctx, botan_view_bin_fn view)
+
+   Generate the prover's key share (shareP), which is sent to the
+   verifier. This can be called only once per prover object.
+
+.. cpp:function:: int botan_spake2p_prover_process_message(botan_spake2p_prover_t prover, \
+                  botan_rng_t rng, const uint8_t peer_message[], size_t peer_message_len, \
+                  botan_view_ctx ctx, botan_view_bin_fn view)
+
+   Consume the verifier's response (shareV followed by confirmV) and
+   produce the prover's key confirmation (confirmP), which is sent to the
+   verifier. Returns ``BOTAN_FFI_ERROR_BAD_MAC`` if the verifier's key
+   confirmation is wrong, typically meaning the passwords do not match.
+
+.. cpp:function:: int botan_spake2p_prover_shared_secret(botan_spake2p_prover_t prover, \
+                  botan_view_ctx ctx, botan_view_bin_fn view)
+
+   Return the shared secret (K_shared). This may be called only after
+   ``botan_spake2p_prover_process_message`` has succeeded.
+
+.. cpp:type:: opaque* botan_spake2p_verifier_t
+
+   An opaque data type for a SPAKE2+ verifier.
+
+.. cpp:function:: int botan_spake2p_verifier_init(botan_spake2p_verifier_t* verifier, \
+                  botan_spake2p_params_t params, \
+                  const uint8_t record[], size_t record_len, \
+                  const uint8_t prover_id[], size_t prover_id_len, \
+                  const uint8_t verifier_id[], size_t verifier_id_len, \
+                  const uint8_t context[], size_t context_len)
+
+   Initialize a verifier from a serialized registration record. See
+   ``botan_spake2p_prover_init`` for the requirements on the identities
+   and context.
+
+.. cpp:function:: int botan_spake2p_verifier_destroy(botan_spake2p_verifier_t verifier)
+
+   Destroy an object.
+
+.. cpp:function:: int botan_spake2p_verifier_process_message(botan_spake2p_verifier_t verifier, \
+                  botan_rng_t rng, const uint8_t peer_message[], size_t peer_message_len, \
+                  botan_view_ctx ctx, botan_view_bin_fn view)
+
+   Consume the prover's key share (shareP) and produce the verifier's
+   response (shareV followed by confirmV), which is sent to the prover.
+   This can be called only once per verifier object.
+
+.. cpp:function:: int botan_spake2p_verifier_verify_confirmation(botan_spake2p_verifier_t verifier, \
+                  const uint8_t confirmation[], size_t confirmation_len)
+
+   Check the prover's key confirmation (confirmP). Returns
+   ``BOTAN_FFI_ERROR_BAD_MAC`` if the confirmation is wrong, meaning the
+   prover does not know the password.
+
+.. cpp:function:: int botan_spake2p_verifier_skip_confirmation(botan_spake2p_verifier_t verifier)
+
+   Can be called after ``botan_spake2p_verifier_process_message``, in
+   place of ``botan_spake2p_verifier_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 ``botan_spake2p_verifier_verify_confirmation``.
+
+.. cpp:function:: int botan_spake2p_verifier_shared_secret(botan_spake2p_verifier_t verifier, \
+                  botan_view_ctx ctx, botan_view_bin_fn view)
+
+   Return the shared secret (K_shared). This may be called only after
+   ``botan_spake2p_verifier_verify_confirmation`` has succeeded, or after
+   ``botan_spake2p_verifier_skip_confirmation``.
+
 ZFEC (Forward Error Correction)
 ----------------------------------------
 

doc/api_ref/python.rst

@@ -723,6 +723,99 @@ HOTP
       in. If the code did verify and resync_range was zero, then the
       next counter will always be counter+1.
 
+SPAKE2+
+-----------------------------------------
+.. versionadded:: 3.13.0
+
+An implementation of the SPAKE2+ password authenticated key exchange
+(RFC 9383). The prover knows the password itself, while the verifier
+stores only a registration record derived from the password.
+
+.. py:class:: Spake2pParams(ciphersuite)
+
+   The system parameters, selecting the elliptic curve group, the SPAKE2+
+   M/N group elements, and the hash function. The ciphersuite is one of
+   "P256-SHA256", "P256-SHA512", "P384-SHA256", "P384-SHA512", or
+   "P521-SHA512".
+
+   .. py:classmethod:: custom(group, seed, hash_fn)
+
+      Create custom system parameters for an arbitrary ``ECGroup``,
+      deriving the M/N group elements from the seed using hash to curve
+      (which not all groups support). Both peers must use the same group,
+      seed, and hash.
+
+   .. py:method:: share_size()
+
+      Return the size in bytes of a key share.
+
+   .. py:method:: confirmation_size()
+
+      Return the size in bytes of a key confirmation message.
+
+.. py:function:: spake2p_derive_secret(params, password, prover_id=b'', verifier_id=b'', salt=b'')
+
+   Derive the prover secret from a password, using Argon2id. The returned
+   secret is password equivalent, and must be protected accordingly.
+
+.. py:function:: spake2p_registration_record(params, secret, rng)
+
+   Compute the registration record for a prover secret, which is provided
+   to the verifier during registration.
+
+.. py:class:: Spake2pProver(params, secret, prover_id=b'', verifier_id=b'', context=b'')
+
+   The identities and context must be agreed upon by both parties; the
+   identities must additionally match the values used when deriving the
+   prover secret.
+
+   .. py:method:: generate_message(rng)
+
+      Generate the prover's key share, which is sent to the verifier.
+      Can be called only once.
+
+   .. py:method:: process_message(peer_message, rng)
+
+      Consume the verifier's response and return the prover's key
+      confirmation, which is sent to the verifier. Raises an exception if
+      the verifier's key confirmation is wrong, typically meaning the
+      passwords do not match.
+
+   .. py:method:: shared_secret()
+
+      Return the shared secret. Only valid after ``process_message``
+      succeeded.
+
+.. py:class:: Spake2pVerifier(params, record, prover_id=b'', verifier_id=b'', context=b'')
+
+   The verifier side of the exchange, using the registration record.
+
+   .. py:method:: process_message(peer_message, rng)
+
+      Consume the prover's key share and return the verifier's response
+      (its own key share followed by a key confirmation), which is sent to
+      the prover. Can be called only once.
+
+   .. py:method:: verify_confirmation(confirmation)
+
+      Check the prover's key confirmation. Raises an exception if the
+      confirmation is wrong, meaning the prover does not know the
+      password.
+
+   .. py:method:: skip_confirmation()
+
+      Skip checking the prover's key confirmation, allowing
+      ``shared_secret`` to be called without ``verify_confirmation``.
+      After calling this, no evidence has been received that the peer
+      knows the password; it is intended solely for protocols which
+      embed SPAKE2+ and perform the prover's key confirmation
+      themselves.
+
+   .. py:method:: shared_secret()
+
+      Return the shared secret. Only valid after ``verify_confirmation``
+      succeeded, or after ``skip_confirmation``.
+
 X509Cert
 -----------------------------------------