SPAKE2+ Key Exchange

(spake2p-derive-secret spake2p-params-obj password prover-id verifier-id salt)

Derive a SPAKE2+ (RFC 9383) prover secret from a password, using Argon2id. The returned secret is password equivalent, and must be protected accordingly. It is used with `spake2p-registration-record` and `spake2p-prover/new`.

(spake2p-params/confirmation-size spake2p-params-obj)

Return the size in bytes of a SPAKE2+ key confirmation message (confirmP or confirmV).

(spake2p-params/new ciphersuite)

Creates a new SPAKE2+ system parameters object from an RFC 9383 `ciphersuite` name, one of "P256-SHA256", "P256-SHA512", "P384-SHA256", "P384-SHA512" or "P521-SHA512". Returns `spake2p-params-obj`.

(spake2p-params/new-custom ec-group-obj seed hash)

Creates a new SPAKE2+ system parameters object for an arbitrary group. `seed` is a byte string from which the M/N group elements are derived using hash to curve, which not all groups support. `hash` is a hash function name (e.g., "SHA-256"). Both peers must use the same group, seed and hash. Returns `spake2p-params-obj`.

(spake2p-params/share-size spake2p-params-obj)

Return the size in bytes of a SPAKE2+ key share (shareP or shareV).

(spake2p-prover/generate-message spake2p-prover-obj &opt rng)

Generate the prover's key share, which is sent to the verifier. Can be called only once. New rng is used by default, if `rng` is not provided.

(spake2p-prover/new spake2p-params-obj secret prover-id verifier-id context)

Creates a SPAKE2+ prover, the side which knows the password. `secret` is the prover secret from `spake2p-derive-secret`. The identities and context must be agreed upon by both parties. Returns `spake2p-prover-obj`.

(spake2p-prover/process-message spake2p-prover-obj peer-message &opt rng)

Consume the verifier's response and return the prover's key confirmation, which is sent to the verifier. Returns nil if the verifier's key confirmation is wrong, typically meaning the passwords do not match. New rng is used by default, if `rng` is not provided.

(spake2p-prover/shared-secret spake2p-prover-obj)

Return the shared secret. Only valid after `spake2p-prover/process-message` succeeded.

(spake2p-registration-record spake2p-params-obj secret &opt rng)

Compute a SPAKE2+ registration record from a prover secret. The registration record is provided to the verifier during registration. New rng is used by default, if `rng` is not provided.

(spake2p-verifier/new spake2p-params-obj record prover-id verifier-id context)

Creates a SPAKE2+ verifier, the side which stores only the registration record derived from the password. `record` is the registration record from `spake2p-registration-record`. The identities and context must be agreed upon by both parties. Returns `spake2p-verifier-obj`.

(spake2p-verifier/process-message spake2p-verifier-obj peer-message &opt 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. New rng is used by default, if `rng` is not provided.

(spake2p-verifier/shared-secret spake2p-verifier-obj)

Return the shared secret. Only valid after `spake2p-verifier/verify-confirmation` succeeded, or after `spake2p-verifier/skip-confirmation`.

(spake2p-verifier/skip-confirmation spake2p-verifier-obj)

Skip checking the prover's key confirmation, allowing `spake2p-verifier/shared-secret` to be called without `spake2p-verifier/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. Returns `spake2p-verifier-obj`.

(spake2p-verifier/verify-confirmation spake2p-verifier-obj confirmation)

Check the prover's key confirmation. Returns false if the confirmation is wrong, meaning the prover does not know the password.