Botan 3.14.1
Crypto and TLS for C&
spake2p.h
Go to the documentation of this file.
1/*
2* (C) 2024,2025,2026 Jack Lloyd
3*
4* Botan is released under the Simplified BSD License (see license.txt)
5*/
6
7#ifndef BOTAN_PAKE_SPAKE2PLUS_H_
8#define BOTAN_PAKE_SPAKE2PLUS_H_
9
10#include <botan/ec_apoint.h>
11#include <botan/ec_group.h>
12#include <botan/ec_scalar.h>
13#include <botan/secmem.h>
14#include <botan/types.h>
15#include <optional>
16#include <span>
17#include <string>
18#include <string_view>
19#include <utility>
20#include <vector>
21
22namespace Botan {
23
25
26}
27
28/**
29* SPAKE2+ (RFC 9383) password authenticated key exchange
30*
31* SPAKE2+ is an augmented PAKE; the two sides are asymmetric. The prover
32* knows the password itself, while the verifier stores only a registration
33* record derived from the password. An attacker who steals the registration
34* record cannot impersonate the prover without first performing a dictionary
35* attack on the record.
36*
37* The expected message flow is
38*
39* - The prover calls ProverContext::generate_message and sends the result
40* (shareP) to the verifier.
41* - The verifier calls VerifierContext::process_message and sends the
42* result (shareV followed by confirmV) to the prover.
43* - The prover calls ProverContext::process_message, which checks the
44* verifier's key confirmation, and sends the result (confirmP) to the
45* verifier.
46* - The verifier calls VerifierContext::verify_confirmation
47*
48* After the final confirmation step both sides can call shared_secret to
49* obtain the session key (K_shared in RFC 9383)
50*
51* Protocols which embed SPAKE2+ and perform the prover's key confirmation
52* themselves (such as the proposed TLS PAKE extension) may instead call
53* VerifierContext::skip_confirmation in place of the final step.
54*/
55namespace Botan::SPAKE2p {
56
57/**
58* SPAKE2+ (RFC 9383) System Parameters
59*
60* This selects the elliptic curve group, the M/N group elements, and the
61* hash function; the hash also fixes the KDF (HKDF) and the MAC (HMAC)
62*/
63class BOTAN_PUBLIC_API(3, 13) SystemParameters final {
64 public:
65 /**
66 * The RFC 9383 ciphersuite P256-SHA256-HKDF-HMAC-SHA256
67 */
68 static SystemParameters rfc9383_p256_sha256();
69
70 /**
71 * The RFC 9383 ciphersuite P256-SHA512-HKDF-HMAC-SHA512
72 */
73 static SystemParameters rfc9383_p256_sha512();
74
75 /**
76 * The RFC 9383 ciphersuite P384-SHA256-HKDF-HMAC-SHA256
77 */
78 static SystemParameters rfc9383_p384_sha256();
79
80 /**
81 * The RFC 9383 ciphersuite P384-SHA512-HKDF-HMAC-SHA512
82 */
83 static SystemParameters rfc9383_p384_sha512();
84
85 /**
86 * The RFC 9383 ciphersuite P521-SHA512-HKDF-HMAC-SHA512
87 */
88 static SystemParameters rfc9383_p521_sha512();
89
90 /**
91 * SPAKE2+ custom system parameters for an arbitrary group
92 *
93 * The M/N values will be derived from the seed using hash2curve;
94 * note that not all groups support hash2curve.
95 *
96 * RFC 9383 Section 3.2: "Applications MAY use different M and N
97 * values, provided they are computed, e.g., using different input
98 * seeds to the algorithm in Appendix B, as random elements for
99 * which the discrete log is unknown."
100 *
101 * If the seed includes the identities of the participants, this
102 * additionally makes the scheme "quantum annoying", in that an attacker
103 * with a discrete logarithm oracle must compute a new discrete log for
104 * each (user, verifier) pair they wish to attack.
105 *
106 * @param group the elliptic curve group to use
107 * @param seed the seed bytes used to derive M and N
108 * @param hash_fn the hash function to use (eg "SHA-256")
109 */
110 static SystemParameters custom(const EC_Group& group, std::span<const uint8_t> seed, std::string_view hash_fn);
111
112 /**
113 * Return the elliptic curve group
114 */
115 const EC_Group& group() const { return m_group; }
116
117 /**
118 * Return the SPAKE2+ M group element
119 */
120 const EC_AffinePoint& spake2p_m() const { return m_spake2p_m; }
121
122 /**
123 * Return the SPAKE2+ N group element
124 */
125 const EC_AffinePoint& spake2p_n() const { return m_spake2p_n; }
126
127 /**
128 * Return the name of the hash function
129 */
130 const std::string& hash_function() const { return m_hash_fn; }
131
132 /**
133 * Return the size in bytes of a key share (shareP or shareV)
134 */
135 size_t share_size() const;
136
137 /**
138 * Return the size in bytes of a key confirmation message (confirmP or confirmV)
139 */
140 size_t confirmation_size() const;
141
142 private:
143 SystemParameters(EC_Group group, EC_AffinePoint m, EC_AffinePoint n, std::string_view hash_fn);
144
145 EC_Group m_group;
146 EC_AffinePoint m_spake2p_m;
147 EC_AffinePoint m_spake2p_n;
148 std::string m_hash_fn;
149};
150
151class ProverSecret;
152
153/**
154* SPAKE2+ Registration Record
155*
156* This is the information (w0 and L in RFC 9383) which the verifier
157* stores in order to authenticate the prover.
158*/
159class BOTAN_PUBLIC_API(3, 13) RegistrationRecord final {
160 public:
161 /**
162 * Perform password registration, returning the registration record
163 *
164 * This derives the record from the password using Argon2id; see
165 * ProverSecret::from_password for the details. The same password,
166 * identities, and salt must later be used to create the prover's secret.
167 *
168 * The identities and salt may be empty.
169 */
170 static RegistrationRecord from_password(const SystemParameters& params,
171 std::string_view password,
172 std::span<const uint8_t> prover_id,
173 std::span<const uint8_t> verifier_id,
174 std::span<const uint8_t> salt,
176
177 /**
178 * Deserialize a RegistrationRecord previously serialized by serialize
179 */
180 static RegistrationRecord deserialize(const SystemParameters& params, std::span<const uint8_t> record);
181
182 /**
183 * Serialize the registration record
184 *
185 * @warning the return value is the unencrypted registration record, which
186 * is a sensitive value allowing password guessing attacks. Encrypt it for
187 * persistent storage if possible.
188 */
190
191 private:
192 friend class ProverSecret;
193 friend class VerifierContext;
194
195 RegistrationRecord(EC_Scalar w0, EC_AffinePoint l) : m_w0(std::move(w0)), m_l(std::move(l)) {}
196
197 EC_Scalar m_w0;
198 EC_AffinePoint m_l;
199};
200
201/**
202* SPAKE2+ Prover Secret
203*
204* This is the information (w0 and w1 in RFC 9383) which the prover
205* derives from the password in order to authenticate itself.
206*/
207class BOTAN_PUBLIC_API(3, 13) ProverSecret final {
208 public:
209 /**
210 * Derive the prover secret from a password
211 *
212 * The derivation uses Argon2id with the memory-constrained parameters
213 * from RFC 9106, namely m=64 MiB, t=3, p=4. Following RFC 9383, the
214 * Argon2id passphrase input is the concatenation
215 *
216 * len(pw) || pw || len(idProver) || idProver || len(idVerifier) || idVerifier
217 *
218 * with each length an 8-byte little-endian count of bytes, and the salt
219 * is provided to Argon2id directly. The Argon2id output is split in two
220 * halves, each of which is reduced modulo the group order.
221 *
222 * The identities and salt may be empty; if a salt is available it
223 * should be used, as this prevents precomputed dictionary attacks.
224 */
225 static ProverSecret from_password(const SystemParameters& params,
226 std::string_view password,
227 std::span<const uint8_t> prover_id,
228 std::span<const uint8_t> verifier_id,
229 std::span<const uint8_t> salt);
230
231 /**
232 * Create a prover secret from already derived scalars
233 *
234 * Throws Invalid_Argument if either scalar is zero.
235 *
236 * @warning This interface is potentially unsafe, depending upon how the
237 * scalars are derived from the password. They must be uniformly random,
238 * and preferably computed in a way such that testing password guesses is
239 * expensive for an attacker. It exists to support testing, as well as
240 * applications which require using a different password hashing scheme
241 * than the default one implemented by from_password.
242 */
243 static ProverSecret from_prehashed(EC_Scalar w0, EC_Scalar w1);
244
245 /**
246 * Deserialize a ProverSecret previously serialized by serialize
247 */
248 static ProverSecret deserialize(const SystemParameters& params, std::span<const uint8_t> secret);
249
250 /**
251 * Serialize the prover secret
252 *
253 * @warning the return value is password equivalent; encrypt it for
254 * persistent storage if possible.
255 */
257
258 /**
259 * Compute the registration record (w0 and L=w1*P) for this secret
260 *
261 * This would typically be done once, when the password is first
262 * registered with the verifier.
263 */
265
266 private:
267 friend class ProverContext;
268
269 ProverSecret(EC_Scalar w0, EC_Scalar w1);
270
271 EC_Scalar m_w0;
272 EC_Scalar m_w1;
273};
274
275/**
276* SPAKE2+ (RFC 9383) Prover
277*
278* The prover knows the password secret (w0 and w1) and authenticates
279* itself to a verifier which knows the matching registration record.
280*/
281class BOTAN_PUBLIC_API(3, 13) ProverContext final {
282 public:
283 /**
284 * Set up for an execution of the protocol
285 *
286 * The identities and context must be agreed upon by both parties; the
287 * identities must additionally match the values used during password
288 * registration. Both the identities and the context may be empty.
289 */
290 ProverContext(const SystemParameters& params,
291 const ProverSecret& secret,
292 std::span<const uint8_t> prover_id,
293 std::span<const uint8_t> verifier_id,
294 std::span<const uint8_t> context = {});
295
296 /**
297 * Generate the prover's key share (shareP), which is sent to the verifier.
298 *
299 * This can be called only once.
300 */
301 std::vector<uint8_t> generate_message(RandomNumberGenerator& rng);
302
303 /**
304 * Consume the message from the verifier (shareV followed by confirmV)
305 * and return the prover's key confirmation (confirmP), which is sent
306 * to the verifier.
307 *
308 * Throws Decoding_Error if the message is malformed, and
309 * Invalid_Authentication_Tag if the verifier's key confirmation is
310 * wrong (typically due to a password mismatch). After any failure
311 * the context cannot be used further.
312 */
313 std::vector<uint8_t> process_message(std::span<const uint8_t> peer_message, RandomNumberGenerator& rng);
314
315 /**
316 * Return the shared secret (K_shared)
317 *
318 * This may be called only after process_message has succeeded.
319 */
321
322 /**
323 * Return the system parameters
324 */
325 const SystemParameters& parameters() const { return m_params; }
326
327 private:
328 enum class State : uint8_t { Initial, ShareGenerated, Complete, Failed };
329
330 SystemParameters m_params;
331 ProverSecret m_secret;
332 std::vector<uint8_t> m_prover_id;
333 std::vector<uint8_t> m_verifier_id;
334 std::vector<uint8_t> m_context;
335 std::optional<std::pair<std::vector<uint8_t>, EC_Scalar>> m_our_message;
336 secure_vector<uint8_t> m_shared_secret;
337 State m_state = State::Initial;
338};
339
340/**
341* SPAKE2+ (RFC 9383) Verifier
342*
343* The verifier does not know the password itself; it stores only the
344* registration record.
345*/
347 public:
348 /**
349 * Set up for an execution of the protocol
350 *
351 * The identities and context must be agreed upon by both parties; the
352 * identities must additionally match the values used during password
353 * registration. Both the identities and the context may be empty.
354 */
355 VerifierContext(const SystemParameters& params,
356 const RegistrationRecord& record,
357 std::span<const uint8_t> prover_id,
358 std::span<const uint8_t> verifier_id,
359 std::span<const uint8_t> context = {});
360
361 /**
362 * Consume the prover's key share (shareP) and return the verifier's
363 * response (shareV followed by confirmV), which is sent to the prover.
364 *
365 * This can be called only once. Throws Decoding_Error if the key
366 * share is malformed, after which the context cannot be used further.
367 */
368 std::vector<uint8_t> process_message(std::span<const uint8_t> peer_message, RandomNumberGenerator& rng);
369
370 /**
371 * Check the prover's key confirmation (confirmP)
372 *
373 * Throws Invalid_Authentication_Tag if the confirmation is wrong,
374 * meaning the prover does not know the password.
375 */
376 void verify_confirmation(std::span<const uint8_t> confirmation);
377
378 /**
379 * Skip checking the prover's key confirmation (confirmP)
380 *
381 * This can be called after process_message, in place of
382 * verify_confirmation, to allow extracting the shared secret without
383 * having checked the prover's key confirmation.
384 *
385 * @warning After calling this, nothing is known about the peer; only
386 * a prover which knows the password can compute the same shared
387 * secret, but no evidence of this has been received. It is intended
388 * solely for protocols which embed SPAKE2+ and perform the prover's
389 * key confirmation themselves, for example the proposed TLS PAKE
390 * extension, where the TLS handshake takes the place of confirmP.
391 * Anywhere else, use verify_confirmation.
392 */
393 void skip_confirmation();
394
395 /**
396 * Return the shared secret (K_shared)
397 *
398 * This may be called only after verify_confirmation has succeeded,
399 * or after skip_confirmation.
400 *
401 * RFC 9383 Section 3.3: "The Verifier MUST NOT send application data
402 * to the Prover until it has received and verified the confirmation
403 * message."
404 */
406
407 /**
408 * Return the system parameters
409 */
410 const SystemParameters& parameters() const { return m_params; }
411
412 private:
413 enum class State : uint8_t { Initial, Responded, Complete, Failed };
414
415 SystemParameters m_params;
416 RegistrationRecord m_record;
417 std::vector<uint8_t> m_prover_id;
418 std::vector<uint8_t> m_verifier_id;
419 std::vector<uint8_t> m_context;
420 std::vector<uint8_t> m_expected_confirmation;
421 secure_vector<uint8_t> m_shared_secret;
422 State m_state = State::Initial;
423};
424
425} // namespace Botan::SPAKE2p
426
427#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
std::vector< uint8_t > process_message(std::span< const uint8_t > peer_message, RandomNumberGenerator &rng)
Definition spake2p.cpp:349
std::vector< uint8_t > generate_message(RandomNumberGenerator &rng)
Definition spake2p.cpp:330
const SystemParameters & parameters() const
Definition spake2p.h:325
secure_vector< uint8_t > shared_secret() const
Definition spake2p.cpp:401
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={})
Definition spake2p.cpp:319
static ProverSecret from_prehashed(EC_Scalar w0, EC_Scalar w1)
Definition spake2p.cpp:297
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)
Definition spake2p.cpp:288
static ProverSecret deserialize(const SystemParameters &params, std::span< const uint8_t > secret)
Definition spake2p.cpp:301
RegistrationRecord registration_record(RandomNumberGenerator &rng) const
Definition spake2p.cpp:313
secure_vector< uint8_t > serialize() const
Definition spake2p.cpp:309
secure_vector< uint8_t > serialize() const
Definition spake2p.cpp:280
static RegistrationRecord deserialize(const SystemParameters &params, std::span< const uint8_t > record)
Definition spake2p.cpp:262
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)
Definition spake2p.cpp:253
const EC_Group & group() const
Definition spake2p.h:115
const EC_AffinePoint & spake2p_n() const
Definition spake2p.h:125
static SystemParameters rfc9383_p256_sha512()
Definition spake2p.cpp:202
static SystemParameters rfc9383_p521_sha512()
Definition spake2p.cpp:217
static SystemParameters rfc9383_p384_sha256()
Definition spake2p.cpp:207
const std::string & hash_function() const
Definition spake2p.h:130
static SystemParameters rfc9383_p256_sha256()
Definition spake2p.cpp:197
static SystemParameters rfc9383_p384_sha512()
Definition spake2p.cpp:212
const EC_AffinePoint & spake2p_m() const
Definition spake2p.h:120
static SystemParameters custom(const EC_Group &group, std::span< const uint8_t > seed, std::string_view hash_fn)
Definition spake2p.cpp:222
std::vector< uint8_t > process_message(std::span< const uint8_t > peer_message, RandomNumberGenerator &rng)
Definition spake2p.cpp:417
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={})
Definition spake2p.cpp:406
const SystemParameters & parameters() const
Definition spake2p.h:410
secure_vector< uint8_t > shared_secret() const
Definition spake2p.cpp:483
void verify_confirmation(std::span< const uint8_t > confirmation)
Definition spake2p.cpp:462
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128