1 /**
2 * \file psa/crypto_extra.h
3 *
4 * \brief PSA cryptography module: Mbed TLS vendor extensions
5 *
6 * \note This file may not be included directly. Applications must
7 * include psa/crypto.h.
8 *
9 * This file is reserved for vendor-specific definitions.
10 */
11 /*
12 * Copyright The Mbed TLS Contributors
13 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
14 */
15
16 #ifndef PSA_CRYPTO_EXTRA_H
17 #define PSA_CRYPTO_EXTRA_H
18 #include "mbedtls/private_access.h"
19
20 #include "crypto_types.h"
21 #include "crypto_compat.h"
22
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26
27 /* UID for secure storage seed */
28 #define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
29
30 /* See mbedtls_config.h for definition */
31 #if !defined(MBEDTLS_PSA_KEY_SLOT_COUNT)
32 #define MBEDTLS_PSA_KEY_SLOT_COUNT 32
33 #endif
34
35 /* If the size of static key slots is not explicitly defined by the user, then
36 * set it to the maximum between PSA_EXPORT_KEY_PAIR_OR_PUBLIC_MAX_SIZE and
37 * PSA_CIPHER_MAX_KEY_LENGTH.
38 * See mbedtls_config.h for the definition. */
39 #if !defined(MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE)
40 #define MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE \
41 ((PSA_EXPORT_KEY_PAIR_OR_PUBLIC_MAX_SIZE > PSA_CIPHER_MAX_KEY_LENGTH) ? \
42 PSA_EXPORT_KEY_PAIR_OR_PUBLIC_MAX_SIZE : PSA_CIPHER_MAX_KEY_LENGTH)
43 #endif /* !MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE*/
44
45 /** \addtogroup attributes
46 * @{
47 */
48
49 /** \brief Declare the enrollment algorithm for a key.
50 *
51 * An operation on a key may indifferently use the algorithm set with
52 * psa_set_key_algorithm() or with this function.
53 *
54 * \param[out] attributes The attribute structure to write to.
55 * \param alg2 A second algorithm that the key may be used
56 * for, in addition to the algorithm set with
57 * psa_set_key_algorithm().
58 *
59 * \warning Setting an enrollment algorithm is not recommended, because
60 * using the same key with different algorithms can allow some
61 * attacks based on arithmetic relations between different
62 * computations made with the same key, or can escalate harmless
63 * side channels into exploitable ones. Use this function only
64 * if it is necessary to support a protocol for which it has been
65 * verified that the usage of the key with multiple algorithms
66 * is safe.
67 */
psa_set_key_enrollment_algorithm(psa_key_attributes_t * attributes,psa_algorithm_t alg2)68 static inline void psa_set_key_enrollment_algorithm(
69 psa_key_attributes_t *attributes,
70 psa_algorithm_t alg2)
71 {
72 attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg2) = alg2;
73 }
74
75 /** Retrieve the enrollment algorithm policy from key attributes.
76 *
77 * \param[in] attributes The key attribute structure to query.
78 *
79 * \return The enrollment algorithm stored in the attribute structure.
80 */
psa_get_key_enrollment_algorithm(const psa_key_attributes_t * attributes)81 static inline psa_algorithm_t psa_get_key_enrollment_algorithm(
82 const psa_key_attributes_t *attributes)
83 {
84 return attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg2);
85 }
86
87 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
88
89 /** Retrieve the slot number where a key is stored.
90 *
91 * A slot number is only defined for keys that are stored in a secure
92 * element.
93 *
94 * This information is only useful if the secure element is not entirely
95 * managed through the PSA Cryptography API. It is up to the secure
96 * element driver to decide how PSA slot numbers map to any other interface
97 * that the secure element may have.
98 *
99 * \param[in] attributes The key attribute structure to query.
100 * \param[out] slot_number On success, the slot number containing the key.
101 *
102 * \retval #PSA_SUCCESS
103 * The key is located in a secure element, and \p *slot_number
104 * indicates the slot number that contains it.
105 * \retval #PSA_ERROR_NOT_PERMITTED
106 * The caller is not permitted to query the slot number.
107 * Mbed TLS currently does not return this error.
108 * \retval #PSA_ERROR_INVALID_ARGUMENT
109 * The key is not located in a secure element.
110 */
111 psa_status_t psa_get_key_slot_number(
112 const psa_key_attributes_t *attributes,
113 psa_key_slot_number_t *slot_number);
114
115 /** Choose the slot number where a key is stored.
116 *
117 * This function declares a slot number in the specified attribute
118 * structure.
119 *
120 * A slot number is only meaningful for keys that are stored in a secure
121 * element. It is up to the secure element driver to decide how PSA slot
122 * numbers map to any other interface that the secure element may have.
123 *
124 * \note Setting a slot number in key attributes for a key creation can
125 * cause the following errors when creating the key:
126 * - #PSA_ERROR_NOT_SUPPORTED if the selected secure element does
127 * not support choosing a specific slot number.
128 * - #PSA_ERROR_NOT_PERMITTED if the caller is not permitted to
129 * choose slot numbers in general or to choose this specific slot.
130 * - #PSA_ERROR_INVALID_ARGUMENT if the chosen slot number is not
131 * valid in general or not valid for this specific key.
132 * - #PSA_ERROR_ALREADY_EXISTS if there is already a key in the
133 * selected slot.
134 *
135 * \param[out] attributes The attribute structure to write to.
136 * \param slot_number The slot number to set.
137 */
psa_set_key_slot_number(psa_key_attributes_t * attributes,psa_key_slot_number_t slot_number)138 static inline void psa_set_key_slot_number(
139 psa_key_attributes_t *attributes,
140 psa_key_slot_number_t slot_number)
141 {
142 attributes->MBEDTLS_PRIVATE(has_slot_number) = 1;
143 attributes->MBEDTLS_PRIVATE(slot_number) = slot_number;
144 }
145
146 /** Remove the slot number attribute from a key attribute structure.
147 *
148 * This function undoes the action of psa_set_key_slot_number().
149 *
150 * \param[out] attributes The attribute structure to write to.
151 */
psa_clear_key_slot_number(psa_key_attributes_t * attributes)152 static inline void psa_clear_key_slot_number(
153 psa_key_attributes_t *attributes)
154 {
155 attributes->MBEDTLS_PRIVATE(has_slot_number) = 0;
156 }
157
158 /** Register a key that is already present in a secure element.
159 *
160 * The key must be located in a secure element designated by the
161 * lifetime field in \p attributes, in the slot set with
162 * psa_set_key_slot_number() in the attribute structure.
163 * This function makes the key available through the key identifier
164 * specified in \p attributes.
165 *
166 * \param[in] attributes The attributes of the existing key.
167 * - The lifetime must be a persistent lifetime
168 * in a secure element. Volatile lifetimes are
169 * not currently supported.
170 * - The key identifier must be in the valid
171 * range for persistent keys.
172 * - The key type and size must be specified and
173 * must be consistent with the key material
174 * in the secure element.
175 *
176 * \retval #PSA_SUCCESS
177 * The key was successfully registered.
178 * Note that depending on the design of the driver, this may or may
179 * not guarantee that a key actually exists in the designated slot
180 * and is compatible with the specified attributes.
181 * \retval #PSA_ERROR_ALREADY_EXISTS
182 * There is already a key with the identifier specified in
183 * \p attributes.
184 * \retval #PSA_ERROR_NOT_SUPPORTED
185 * The secure element driver for the specified lifetime does not
186 * support registering a key.
187 * \retval #PSA_ERROR_INVALID_ARGUMENT
188 * The identifier in \p attributes is invalid, namely the identifier is
189 * not in the user range, or
190 * \p attributes specifies a lifetime which is not located
191 * in a secure element, or no slot number is specified in \p attributes,
192 * or the specified slot number is not valid.
193 * \retval #PSA_ERROR_NOT_PERMITTED
194 * The caller is not authorized to register the specified key slot.
195 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
196 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription
197 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
198 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
199 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
200 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
201 * \retval #PSA_ERROR_BAD_STATE
202 * The library has not been previously initialized by psa_crypto_init().
203 * It is implementation-dependent whether a failure to initialize
204 * results in this error code.
205 */
206 psa_status_t mbedtls_psa_register_se_key(
207 const psa_key_attributes_t *attributes);
208
209 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */
210
211 /**@}*/
212
213 /**
214 * \brief Library deinitialization.
215 *
216 * This function clears all data associated with the PSA layer,
217 * including the whole key store.
218 * This function is not thread safe, it wipes every key slot regardless of
219 * state and reader count. It should only be called when no slot is in use.
220 *
221 * This is an Mbed TLS extension.
222 */
223 void mbedtls_psa_crypto_free(void);
224
225 /** \brief Statistics about
226 * resource consumption related to the PSA keystore.
227 *
228 * \note The content of this structure is not part of the stable API and ABI
229 * of Mbed TLS and may change arbitrarily from version to version.
230 */
231 typedef struct mbedtls_psa_stats_s {
232 /** Number of slots containing key material for a volatile key. */
233 size_t MBEDTLS_PRIVATE(volatile_slots);
234 /** Number of slots containing key material for a key which is in
235 * internal persistent storage. */
236 size_t MBEDTLS_PRIVATE(persistent_slots);
237 /** Number of slots containing a reference to a key in a
238 * secure element. */
239 size_t MBEDTLS_PRIVATE(external_slots);
240 /** Number of slots which are occupied, but do not contain
241 * key material yet. */
242 size_t MBEDTLS_PRIVATE(half_filled_slots);
243 /** Number of slots that contain cache data. */
244 size_t MBEDTLS_PRIVATE(cache_slots);
245 /** Number of slots that are not used for anything. */
246 size_t MBEDTLS_PRIVATE(empty_slots);
247 /** Number of slots that are locked. */
248 size_t MBEDTLS_PRIVATE(locked_slots);
249 /** Largest key id value among open keys in internal persistent storage. */
250 psa_key_id_t MBEDTLS_PRIVATE(max_open_internal_key_id);
251 /** Largest key id value among open keys in secure elements. */
252 psa_key_id_t MBEDTLS_PRIVATE(max_open_external_key_id);
253 } mbedtls_psa_stats_t;
254
255 /** \brief Get statistics about
256 * resource consumption related to the PSA keystore.
257 *
258 * \note When Mbed TLS is built as part of a service, with isolation
259 * between the application and the keystore, the service may or
260 * may not expose this function.
261 */
262 void mbedtls_psa_get_stats(mbedtls_psa_stats_t *stats);
263
264 /**
265 * \brief Inject an initial entropy seed for the random generator into
266 * secure storage.
267 *
268 * This function injects data to be used as a seed for the random generator
269 * used by the PSA Crypto implementation. On devices that lack a trusted
270 * entropy source (preferably a hardware random number generator),
271 * the Mbed PSA Crypto implementation uses this value to seed its
272 * random generator.
273 *
274 * On devices without a trusted entropy source, this function must be
275 * called exactly once in the lifetime of the device. On devices with
276 * a trusted entropy source, calling this function is optional.
277 * In all cases, this function may only be called before calling any
278 * other function in the PSA Crypto API, including psa_crypto_init().
279 *
280 * When this function returns successfully, it populates a file in
281 * persistent storage. Once the file has been created, this function
282 * can no longer succeed.
283 *
284 * If any error occurs, this function does not change the system state.
285 * You can call this function again after correcting the reason for the
286 * error if possible.
287 *
288 * \warning This function **can** fail! Callers MUST check the return status.
289 *
290 * \warning If you use this function, you should use it as part of a
291 * factory provisioning process. The value of the injected seed
292 * is critical to the security of the device. It must be
293 * *secret*, *unpredictable* and (statistically) *unique per device*.
294 * You should be generate it randomly using a cryptographically
295 * secure random generator seeded from trusted entropy sources.
296 * You should transmit it securely to the device and ensure
297 * that its value is not leaked or stored anywhere beyond the
298 * needs of transmitting it from the point of generation to
299 * the call of this function, and erase all copies of the value
300 * once this function returns.
301 *
302 * This is an Mbed TLS extension.
303 *
304 * \note This function is only available on the following platforms:
305 * * If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled.
306 * Note that you must provide compatible implementations of
307 * mbedtls_nv_seed_read and mbedtls_nv_seed_write.
308 * * In a client-server integration of PSA Cryptography, on the client side,
309 * if the server supports this feature.
310 * \param[in] seed Buffer containing the seed value to inject.
311 * \param[in] seed_size Size of the \p seed buffer.
312 * The size of the seed in bytes must be greater
313 * or equal to both #MBEDTLS_ENTROPY_BLOCK_SIZE
314 * and the value of \c MBEDTLS_ENTROPY_MIN_PLATFORM
315 * in `library/entropy_poll.h` in the Mbed TLS source
316 * code.
317 * It must be less or equal to
318 * #MBEDTLS_ENTROPY_MAX_SEED_SIZE.
319 *
320 * \retval #PSA_SUCCESS
321 * The seed value was injected successfully. The random generator
322 * of the PSA Crypto implementation is now ready for use.
323 * You may now call psa_crypto_init() and use the PSA Crypto
324 * implementation.
325 * \retval #PSA_ERROR_INVALID_ARGUMENT
326 * \p seed_size is out of range.
327 * \retval #PSA_ERROR_STORAGE_FAILURE
328 * There was a failure reading or writing from storage.
329 * \retval #PSA_ERROR_NOT_PERMITTED
330 * The library has already been initialized. It is no longer
331 * possible to call this function.
332 */
333 psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed,
334 size_t seed_size);
335
336 /** \addtogroup crypto_types
337 * @{
338 */
339
340 /** DSA public key.
341 *
342 * The import and export format is the
343 * representation of the public key `y = g^x mod p` as a big-endian byte
344 * string. The length of the byte string is the length of the base prime `p`
345 * in bytes.
346 */
347 #define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t) 0x4002)
348
349 /** DSA key pair (private and public key).
350 *
351 * The import and export format is the
352 * representation of the private key `x` as a big-endian byte string. The
353 * length of the byte string is the private key size in bytes (leading zeroes
354 * are not stripped).
355 *
356 * Deterministic DSA key derivation with psa_generate_derived_key follows
357 * FIPS 186-4 §B.1.2: interpret the byte string as integer
358 * in big-endian order. Discard it if it is not in the range
359 * [0, *N* - 2] where *N* is the boundary of the private key domain
360 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
361 * or the order of the curve's base point for ECC).
362 * Add 1 to the resulting integer and use this as the private key *x*.
363 *
364 */
365 #define PSA_KEY_TYPE_DSA_KEY_PAIR ((psa_key_type_t) 0x7002)
366
367 /** Whether a key type is a DSA key (pair or public-only). */
368 #define PSA_KEY_TYPE_IS_DSA(type) \
369 (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY)
370
371 #define PSA_ALG_DSA_BASE ((psa_algorithm_t) 0x06000400)
372 /** DSA signature with hashing.
373 *
374 * This is the signature scheme defined by FIPS 186-4,
375 * with a random per-message secret number (*k*).
376 *
377 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
378 * #PSA_ALG_IS_HASH(\p hash_alg) is true).
379 * This includes #PSA_ALG_ANY_HASH
380 * when specifying the algorithm in a usage policy.
381 *
382 * \return The corresponding DSA signature algorithm.
383 * \return Unspecified if \p hash_alg is not a supported
384 * hash algorithm.
385 */
386 #define PSA_ALG_DSA(hash_alg) \
387 (PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
388 #define PSA_ALG_DETERMINISTIC_DSA_BASE ((psa_algorithm_t) 0x06000500)
389 #define PSA_ALG_DSA_DETERMINISTIC_FLAG PSA_ALG_ECDSA_DETERMINISTIC_FLAG
390 /** Deterministic DSA signature with hashing.
391 *
392 * This is the deterministic variant defined by RFC 6979 of
393 * the signature scheme defined by FIPS 186-4.
394 *
395 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
396 * #PSA_ALG_IS_HASH(\p hash_alg) is true).
397 * This includes #PSA_ALG_ANY_HASH
398 * when specifying the algorithm in a usage policy.
399 *
400 * \return The corresponding DSA signature algorithm.
401 * \return Unspecified if \p hash_alg is not a supported
402 * hash algorithm.
403 */
404 #define PSA_ALG_DETERMINISTIC_DSA(hash_alg) \
405 (PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
406 #define PSA_ALG_IS_DSA(alg) \
407 (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) == \
408 PSA_ALG_DSA_BASE)
409 #define PSA_ALG_DSA_IS_DETERMINISTIC(alg) \
410 (((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0)
411 #define PSA_ALG_IS_DETERMINISTIC_DSA(alg) \
412 (PSA_ALG_IS_DSA(alg) && PSA_ALG_DSA_IS_DETERMINISTIC(alg))
413 #define PSA_ALG_IS_RANDOMIZED_DSA(alg) \
414 (PSA_ALG_IS_DSA(alg) && !PSA_ALG_DSA_IS_DETERMINISTIC(alg))
415
416
417 /* We need to expand the sample definition of this macro from
418 * the API definition. */
419 #undef PSA_ALG_IS_VENDOR_HASH_AND_SIGN
420 #define PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg) \
421 PSA_ALG_IS_DSA(alg)
422
423 /**@}*/
424
425 /** \addtogroup attributes
426 * @{
427 */
428
429 /** PAKE operation stages. */
430 #define PSA_PAKE_OPERATION_STAGE_SETUP 0
431 #define PSA_PAKE_OPERATION_STAGE_COLLECT_INPUTS 1
432 #define PSA_PAKE_OPERATION_STAGE_COMPUTATION 2
433
434 /**@}*/
435
436
437 /** \defgroup psa_external_rng External random generator
438 * @{
439 */
440
441 #if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
442 /** External random generator function, implemented by the platform.
443 *
444 * When the compile-time option #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled,
445 * this function replaces Mbed TLS's entropy and DRBG modules for all
446 * random generation triggered via PSA crypto interfaces.
447 *
448 * \note This random generator must deliver random numbers with cryptographic
449 * quality and high performance. It must supply unpredictable numbers
450 * with a uniform distribution. The implementation of this function
451 * is responsible for ensuring that the random generator is seeded
452 * with sufficient entropy. If you have a hardware TRNG which is slow
453 * or delivers non-uniform output, declare it as an entropy source
454 * with mbedtls_entropy_add_source() instead of enabling this option.
455 *
456 * \param[in,out] context Pointer to the random generator context.
457 * This is all-bits-zero on the first call
458 * and preserved between successive calls.
459 * \param[out] output Output buffer. On success, this buffer
460 * contains random data with a uniform
461 * distribution.
462 * \param output_size The size of the \p output buffer in bytes.
463 * \param[out] output_length On success, set this value to \p output_size.
464 *
465 * \retval #PSA_SUCCESS
466 * Success. The output buffer contains \p output_size bytes of
467 * cryptographic-quality random data, and \c *output_length is
468 * set to \p output_size.
469 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
470 * The random generator requires extra entropy and there is no
471 * way to obtain entropy under current environment conditions.
472 * This error should not happen under normal circumstances since
473 * this function is responsible for obtaining as much entropy as
474 * it needs. However implementations of this function may return
475 * #PSA_ERROR_INSUFFICIENT_ENTROPY if there is no way to obtain
476 * entropy without blocking indefinitely.
477 * \retval #PSA_ERROR_HARDWARE_FAILURE
478 * A failure of the random generator hardware that isn't covered
479 * by #PSA_ERROR_INSUFFICIENT_ENTROPY.
480 */
481 psa_status_t mbedtls_psa_external_get_random(
482 mbedtls_psa_external_random_context_t *context,
483 uint8_t *output, size_t output_size, size_t *output_length);
484 #endif /* MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */
485
486 /**@}*/
487
488 /** \defgroup psa_builtin_keys Built-in keys
489 * @{
490 */
491
492 /** The minimum value for a key identifier that is built into the
493 * implementation.
494 *
495 * The range of key identifiers from #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN
496 * to #MBEDTLS_PSA_KEY_ID_BUILTIN_MAX within the range from
497 * #PSA_KEY_ID_VENDOR_MIN and #PSA_KEY_ID_VENDOR_MAX and must not intersect
498 * with any other set of implementation-chosen key identifiers.
499 *
500 * This value is part of the library's API since changing it would invalidate
501 * the values of built-in key identifiers in applications.
502 */
503 #define MBEDTLS_PSA_KEY_ID_BUILTIN_MIN ((psa_key_id_t) 0x7fff0000)
504
505 /** The maximum value for a key identifier that is built into the
506 * implementation.
507 *
508 * See #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN for more information.
509 */
510 #define MBEDTLS_PSA_KEY_ID_BUILTIN_MAX ((psa_key_id_t) 0x7fffefff)
511
512 /** A slot number identifying a key in a driver.
513 *
514 * Values of this type are used to identify built-in keys.
515 */
516 typedef uint64_t psa_drv_slot_number_t;
517
518 #if defined(MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS)
519 /** Test whether a key identifier belongs to the builtin key range.
520 *
521 * \param key_id Key identifier to test.
522 *
523 * \retval 1
524 * The key identifier is a builtin key identifier.
525 * \retval 0
526 * The key identifier is not a builtin key identifier.
527 */
psa_key_id_is_builtin(psa_key_id_t key_id)528 static inline int psa_key_id_is_builtin(psa_key_id_t key_id)
529 {
530 return (key_id >= MBEDTLS_PSA_KEY_ID_BUILTIN_MIN) &&
531 (key_id <= MBEDTLS_PSA_KEY_ID_BUILTIN_MAX);
532 }
533
534 /** Platform function to obtain the location and slot number of a built-in key.
535 *
536 * An application-specific implementation of this function must be provided if
537 * #MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS is enabled. This would typically be provided
538 * as part of a platform's system image.
539 *
540 * #MBEDTLS_SVC_KEY_ID_GET_KEY_ID(\p key_id) needs to be in the range from
541 * #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN to #MBEDTLS_PSA_KEY_ID_BUILTIN_MAX.
542 *
543 * In a multi-application configuration
544 * (\c MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER is defined),
545 * this function should check that #MBEDTLS_SVC_KEY_ID_GET_OWNER_ID(\p key_id)
546 * is allowed to use the given key.
547 *
548 * \param key_id The key ID for which to retrieve the
549 * location and slot attributes.
550 * \param[out] lifetime On success, the lifetime associated with the key
551 * corresponding to \p key_id. Lifetime is a
552 * combination of which driver contains the key,
553 * and with what persistence level the key is
554 * intended to be used. If the platform
555 * implementation does not contain specific
556 * information about the intended key persistence
557 * level, the persistence level may be reported as
558 * #PSA_KEY_PERSISTENCE_DEFAULT.
559 * \param[out] slot_number On success, the slot number known to the driver
560 * registered at the lifetime location reported
561 * through \p lifetime which corresponds to the
562 * requested built-in key.
563 *
564 * \retval #PSA_SUCCESS
565 * The requested key identifier designates a built-in key.
566 * In a multi-application configuration, the requested owner
567 * is allowed to access it.
568 * \retval #PSA_ERROR_DOES_NOT_EXIST
569 * The requested key identifier is not a built-in key which is known
570 * to this function. If a key exists in the key storage with this
571 * identifier, the data from the storage will be used.
572 * \return (any other error)
573 * Any other error is propagated to the function that requested the key.
574 * Common errors include:
575 * - #PSA_ERROR_NOT_PERMITTED: the key exists but the requested owner
576 * is not allowed to access it.
577 */
578 psa_status_t mbedtls_psa_platform_get_builtin_key(
579 mbedtls_svc_key_id_t key_id,
580 psa_key_lifetime_t *lifetime,
581 psa_drv_slot_number_t *slot_number);
582 #endif /* MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS */
583
584 /** @} */
585
586 /** \defgroup psa_crypto_client Functions defined by a client provider
587 *
588 * The functions in this group are meant to be implemented by providers of
589 * the PSA Crypto client interface. They are provided by the library when
590 * #MBEDTLS_PSA_CRYPTO_C is enabled.
591 *
592 * \note All functions in this group are experimental, as using
593 * alternative client interface providers is experimental.
594 *
595 * @{
596 */
597
598 /** Check if PSA is capable of handling the specified hash algorithm.
599 *
600 * This means that PSA core was built with the corresponding PSA_WANT_ALG_xxx
601 * set and that psa_crypto_init has already been called.
602 *
603 * \note When using the built-in version of the PSA core (i.e.
604 * #MBEDTLS_PSA_CRYPTO_C is set), for now, this function only checks
605 * the state of the driver subsystem, not the algorithm.
606 * This might be improved in the future.
607 *
608 * \param hash_alg The hash algorithm.
609 *
610 * \return 1 if the PSA can handle \p hash_alg, 0 otherwise.
611 */
612 int psa_can_do_hash(psa_algorithm_t hash_alg);
613
614 /**
615 * Tell if PSA is ready for this cipher.
616 *
617 * \note When using the built-in version of the PSA core (i.e.
618 * #MBEDTLS_PSA_CRYPTO_C is set), for now, this function only checks
619 * the state of the driver subsystem, not the key type and algorithm.
620 * This might be improved in the future.
621 *
622 * \param key_type The key type.
623 * \param cipher_alg The cipher algorithm.
624 *
625 * \return 1 if the PSA can handle \p cipher_alg, 0 otherwise.
626 */
627 int psa_can_do_cipher(psa_key_type_t key_type, psa_algorithm_t cipher_alg);
628
629 /**@}*/
630
631 /** \addtogroup crypto_types
632 * @{
633 */
634
635 #define PSA_ALG_CATEGORY_PAKE ((psa_algorithm_t) 0x0a000000)
636
637 /** Whether the specified algorithm is a password-authenticated key exchange.
638 *
639 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
640 *
641 * \return 1 if \p alg is a password-authenticated key exchange (PAKE)
642 * algorithm, 0 otherwise.
643 * This macro may return either 0 or 1 if \p alg is not a supported
644 * algorithm identifier.
645 */
646 #define PSA_ALG_IS_PAKE(alg) \
647 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_PAKE)
648
649 /** The Password-authenticated key exchange by juggling (J-PAKE) algorithm.
650 *
651 * This is J-PAKE as defined by RFC 8236, instantiated with the following
652 * parameters:
653 *
654 * - The group can be either an elliptic curve or defined over a finite field.
655 * - Schnorr NIZK proof as defined by RFC 8235 and using the same group as the
656 * J-PAKE algorithm.
657 * - A cryptographic hash function.
658 *
659 * To select these parameters and set up the cipher suite, call these functions
660 * in any order:
661 *
662 * \code
663 * psa_pake_cs_set_algorithm(cipher_suite, PSA_ALG_JPAKE);
664 * psa_pake_cs_set_primitive(cipher_suite,
665 * PSA_PAKE_PRIMITIVE(type, family, bits));
666 * psa_pake_cs_set_hash(cipher_suite, hash);
667 * \endcode
668 *
669 * For more information on how to set a specific curve or field, refer to the
670 * documentation of the individual \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
671 *
672 * After initializing a J-PAKE operation, call
673 *
674 * \code
675 * psa_pake_setup(operation, cipher_suite);
676 * psa_pake_set_user(operation, ...);
677 * psa_pake_set_peer(operation, ...);
678 * psa_pake_set_password_key(operation, ...);
679 * \endcode
680 *
681 * The password is provided as a key. This can be the password text itself,
682 * in an agreed character encoding, or some value derived from the password
683 * as required by a higher level protocol.
684 *
685 * (The implementation converts the key material to a number as described in
686 * Section 2.3.8 of _SEC 1: Elliptic Curve Cryptography_
687 * (https://www.secg.org/sec1-v2.pdf), before reducing it modulo \c q. Here
688 * \c q is order of the group defined by the primitive set in the cipher suite.
689 * The \c psa_pake_set_password_key() function returns an error if the result
690 * of the reduction is 0.)
691 *
692 * The key exchange flow for J-PAKE is as follows:
693 * -# To get the first round data that needs to be sent to the peer, call
694 * \code
695 * // Get g1
696 * psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
697 * // Get the ZKP public key for x1
698 * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
699 * // Get the ZKP proof for x1
700 * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
701 * // Get g2
702 * psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
703 * // Get the ZKP public key for x2
704 * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
705 * // Get the ZKP proof for x2
706 * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
707 * \endcode
708 * -# To provide the first round data received from the peer to the operation,
709 * call
710 * \code
711 * // Set g3
712 * psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
713 * // Set the ZKP public key for x3
714 * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
715 * // Set the ZKP proof for x3
716 * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
717 * // Set g4
718 * psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
719 * // Set the ZKP public key for x4
720 * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
721 * // Set the ZKP proof for x4
722 * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
723 * \endcode
724 * -# To get the second round data that needs to be sent to the peer, call
725 * \code
726 * // Get A
727 * psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
728 * // Get ZKP public key for x2*s
729 * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
730 * // Get ZKP proof for x2*s
731 * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
732 * \endcode
733 * -# To provide the second round data received from the peer to the operation,
734 * call
735 * \code
736 * // Set B
737 * psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
738 * // Set ZKP public key for x4*s
739 * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
740 * // Set ZKP proof for x4*s
741 * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
742 * \endcode
743 * -# To access the shared secret call
744 * \code
745 * // Get Ka=Kb=K
746 * psa_pake_get_implicit_key()
747 * \endcode
748 *
749 * For more information consult the documentation of the individual
750 * \c PSA_PAKE_STEP_XXX constants.
751 *
752 * At this point there is a cryptographic guarantee that only the authenticated
753 * party who used the same password is able to compute the key. But there is no
754 * guarantee that the peer is the party it claims to be and was able to do so.
755 *
756 * That is, the authentication is only implicit (the peer is not authenticated
757 * at this point, and no action should be taken that assume that they are - like
758 * for example accessing restricted files).
759 *
760 * To make the authentication explicit there are various methods, see Section 5
761 * of RFC 8236 for two examples.
762 *
763 * \note The JPAKE implementation has the following limitations:
764 * - The only supported primitive is ECC on the curve secp256r1, i.e.
765 * `PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC,
766 * PSA_ECC_FAMILY_SECP_R1, 256)`.
767 * - The only supported hash algorithm is SHA-256, i.e.
768 * `PSA_ALG_SHA_256`.
769 * - When using the built-in implementation, the user ID and the peer ID
770 * must be `"client"` (6-byte string) and `"server"` (6-byte string),
771 * or the other way round.
772 * Third-party drivers may or may not have this limitation.
773 *
774 */
775 #define PSA_ALG_JPAKE ((psa_algorithm_t) 0x0a000100)
776
777 /** @} */
778
779 /** \defgroup pake Password-authenticated key exchange (PAKE)
780 *
781 * This is a proposed PAKE interface for the PSA Crypto API. It is not part of
782 * the official PSA Crypto API yet.
783 *
784 * \note The content of this section is not part of the stable API and ABI
785 * of Mbed TLS and may change arbitrarily from version to version.
786 * Same holds for the corresponding macros #PSA_ALG_CATEGORY_PAKE and
787 * #PSA_ALG_JPAKE.
788 * @{
789 */
790
791 /** \brief Encoding of the application role of PAKE
792 *
793 * Encodes the application's role in the algorithm is being executed. For more
794 * information see the documentation of individual \c PSA_PAKE_ROLE_XXX
795 * constants.
796 */
797 typedef uint8_t psa_pake_role_t;
798
799 /** Encoding of input and output indicators for PAKE.
800 *
801 * Some PAKE algorithms need to exchange more data than just a single key share.
802 * This type is for encoding additional input and output data for such
803 * algorithms.
804 */
805 typedef uint8_t psa_pake_step_t;
806
807 /** Encoding of the type of the PAKE's primitive.
808 *
809 * Values defined by this standard will never be in the range 0x80-0xff.
810 * Vendors who define additional types must use an encoding in this range.
811 *
812 * For more information see the documentation of individual
813 * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
814 */
815 typedef uint8_t psa_pake_primitive_type_t;
816
817 /** \brief Encoding of the family of the primitive associated with the PAKE.
818 *
819 * For more information see the documentation of individual
820 * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
821 */
822 typedef uint8_t psa_pake_family_t;
823
824 /** \brief Encoding of the primitive associated with the PAKE.
825 *
826 * For more information see the documentation of the #PSA_PAKE_PRIMITIVE macro.
827 */
828 typedef uint32_t psa_pake_primitive_t;
829
830 /** A value to indicate no role in a PAKE algorithm.
831 * This value can be used in a call to psa_pake_set_role() for symmetric PAKE
832 * algorithms which do not assign roles.
833 */
834 #define PSA_PAKE_ROLE_NONE ((psa_pake_role_t) 0x00)
835
836 /** The first peer in a balanced PAKE.
837 *
838 * Although balanced PAKE algorithms are symmetric, some of them needs an
839 * ordering of peers for the transcript calculations. If the algorithm does not
840 * need this, both #PSA_PAKE_ROLE_FIRST and #PSA_PAKE_ROLE_SECOND are
841 * accepted.
842 */
843 #define PSA_PAKE_ROLE_FIRST ((psa_pake_role_t) 0x01)
844
845 /** The second peer in a balanced PAKE.
846 *
847 * Although balanced PAKE algorithms are symmetric, some of them needs an
848 * ordering of peers for the transcript calculations. If the algorithm does not
849 * need this, either #PSA_PAKE_ROLE_FIRST or #PSA_PAKE_ROLE_SECOND are
850 * accepted.
851 */
852 #define PSA_PAKE_ROLE_SECOND ((psa_pake_role_t) 0x02)
853
854 /** The client in an augmented PAKE.
855 *
856 * Augmented PAKE algorithms need to differentiate between client and server.
857 */
858 #define PSA_PAKE_ROLE_CLIENT ((psa_pake_role_t) 0x11)
859
860 /** The server in an augmented PAKE.
861 *
862 * Augmented PAKE algorithms need to differentiate between client and server.
863 */
864 #define PSA_PAKE_ROLE_SERVER ((psa_pake_role_t) 0x12)
865
866 /** The PAKE primitive type indicating the use of elliptic curves.
867 *
868 * The values of the \c family and \c bits fields of the cipher suite identify a
869 * specific elliptic curve, using the same mapping that is used for ECC
870 * (::psa_ecc_family_t) keys.
871 *
872 * (Here \c family means the value returned by psa_pake_cs_get_family() and
873 * \c bits means the value returned by psa_pake_cs_get_bits().)
874 *
875 * Input and output during the operation can involve group elements and scalar
876 * values:
877 * -# The format for group elements is the same as for public keys on the
878 * specific curve would be. For more information, consult the documentation of
879 * psa_export_public_key().
880 * -# The format for scalars is the same as for private keys on the specific
881 * curve would be. For more information, consult the documentation of
882 * psa_export_key().
883 */
884 #define PSA_PAKE_PRIMITIVE_TYPE_ECC ((psa_pake_primitive_type_t) 0x01)
885
886 /** The PAKE primitive type indicating the use of Diffie-Hellman groups.
887 *
888 * The values of the \c family and \c bits fields of the cipher suite identify
889 * a specific Diffie-Hellman group, using the same mapping that is used for
890 * Diffie-Hellman (::psa_dh_family_t) keys.
891 *
892 * (Here \c family means the value returned by psa_pake_cs_get_family() and
893 * \c bits means the value returned by psa_pake_cs_get_bits().)
894 *
895 * Input and output during the operation can involve group elements and scalar
896 * values:
897 * -# The format for group elements is the same as for public keys on the
898 * specific group would be. For more information, consult the documentation of
899 * psa_export_public_key().
900 * -# The format for scalars is the same as for private keys on the specific
901 * group would be. For more information, consult the documentation of
902 * psa_export_key().
903 */
904 #define PSA_PAKE_PRIMITIVE_TYPE_DH ((psa_pake_primitive_type_t) 0x02)
905
906 /** Construct a PAKE primitive from type, family and bit-size.
907 *
908 * \param pake_type The type of the primitive
909 * (value of type ::psa_pake_primitive_type_t).
910 * \param pake_family The family of the primitive
911 * (the type and interpretation of this parameter depends
912 * on \p pake_type, for more information consult the
913 * documentation of individual ::psa_pake_primitive_type_t
914 * constants).
915 * \param pake_bits The bit-size of the primitive
916 * (Value of type \c size_t. The interpretation
917 * of this parameter depends on \p pake_family, for more
918 * information consult the documentation of individual
919 * ::psa_pake_primitive_type_t constants).
920 *
921 * \return The constructed primitive value of type ::psa_pake_primitive_t.
922 * Return 0 if the requested primitive can't be encoded as
923 * ::psa_pake_primitive_t.
924 */
925 #define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits) \
926 ((pake_bits & 0xFFFF) != pake_bits) ? 0 : \
927 ((psa_pake_primitive_t) (((pake_type) << 24 | \
928 (pake_family) << 16) | (pake_bits)))
929
930 /** The key share being sent to or received from the peer.
931 *
932 * The format for both input and output at this step is the same as for public
933 * keys on the group determined by the primitive (::psa_pake_primitive_t) would
934 * be.
935 *
936 * For more information on the format, consult the documentation of
937 * psa_export_public_key().
938 *
939 * For information regarding how the group is determined, consult the
940 * documentation #PSA_PAKE_PRIMITIVE.
941 */
942 #define PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t) 0x01)
943
944 /** A Schnorr NIZKP public key.
945 *
946 * This is the ephemeral public key in the Schnorr Non-Interactive
947 * Zero-Knowledge Proof (the value denoted by the letter 'V' in RFC 8235).
948 *
949 * The format for both input and output at this step is the same as for public
950 * keys on the group determined by the primitive (::psa_pake_primitive_t) would
951 * be.
952 *
953 * For more information on the format, consult the documentation of
954 * psa_export_public_key().
955 *
956 * For information regarding how the group is determined, consult the
957 * documentation #PSA_PAKE_PRIMITIVE.
958 */
959 #define PSA_PAKE_STEP_ZK_PUBLIC ((psa_pake_step_t) 0x02)
960
961 /** A Schnorr NIZKP proof.
962 *
963 * This is the proof in the Schnorr Non-Interactive Zero-Knowledge Proof (the
964 * value denoted by the letter 'r' in RFC 8235).
965 *
966 * Both for input and output, the value at this step is an integer less than
967 * the order of the group selected in the cipher suite. The format depends on
968 * the group as well:
969 *
970 * - For Montgomery curves, the encoding is little endian.
971 * - For everything else the encoding is big endian (see Section 2.3.8 of
972 * _SEC 1: Elliptic Curve Cryptography_ at https://www.secg.org/sec1-v2.pdf).
973 *
974 * In both cases leading zeroes are allowed as long as the length in bytes does
975 * not exceed the byte length of the group order.
976 *
977 * For information regarding how the group is determined, consult the
978 * documentation #PSA_PAKE_PRIMITIVE.
979 */
980 #define PSA_PAKE_STEP_ZK_PROOF ((psa_pake_step_t) 0x03)
981
982 /**@}*/
983
984 /** A sufficient output buffer size for psa_pake_output().
985 *
986 * If the size of the output buffer is at least this large, it is guaranteed
987 * that psa_pake_output() will not fail due to an insufficient output buffer
988 * size. The actual size of the output might be smaller in any given call.
989 *
990 * See also #PSA_PAKE_OUTPUT_MAX_SIZE
991 *
992 * \param alg A PAKE algorithm (\c PSA_ALG_XXX value such that
993 * #PSA_ALG_IS_PAKE(\p alg) is true).
994 * \param primitive A primitive of type ::psa_pake_primitive_t that is
995 * compatible with algorithm \p alg.
996 * \param output_step A value of type ::psa_pake_step_t that is valid for the
997 * algorithm \p alg.
998 * \return A sufficient output buffer size for the specified
999 * PAKE algorithm, primitive, and output step. If the
1000 * PAKE algorithm, primitive, or output step is not
1001 * recognized, or the parameters are incompatible,
1002 * return 0.
1003 */
1004 #define PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step) \
1005 (alg == PSA_ALG_JPAKE && \
1006 primitive == PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC, \
1007 PSA_ECC_FAMILY_SECP_R1, 256) ? \
1008 ( \
1009 output_step == PSA_PAKE_STEP_KEY_SHARE ? 65 : \
1010 output_step == PSA_PAKE_STEP_ZK_PUBLIC ? 65 : \
1011 32 \
1012 ) : \
1013 0)
1014
1015 /** A sufficient input buffer size for psa_pake_input().
1016 *
1017 * The value returned by this macro is guaranteed to be large enough for any
1018 * valid input to psa_pake_input() in an operation with the specified
1019 * parameters.
1020 *
1021 * See also #PSA_PAKE_INPUT_MAX_SIZE
1022 *
1023 * \param alg A PAKE algorithm (\c PSA_ALG_XXX value such that
1024 * #PSA_ALG_IS_PAKE(\p alg) is true).
1025 * \param primitive A primitive of type ::psa_pake_primitive_t that is
1026 * compatible with algorithm \p alg.
1027 * \param input_step A value of type ::psa_pake_step_t that is valid for the
1028 * algorithm \p alg.
1029 * \return A sufficient input buffer size for the specified
1030 * input, cipher suite and algorithm. If the cipher suite,
1031 * the input type or PAKE algorithm is not recognized, or
1032 * the parameters are incompatible, return 0.
1033 */
1034 #define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step) \
1035 (alg == PSA_ALG_JPAKE && \
1036 primitive == PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC, \
1037 PSA_ECC_FAMILY_SECP_R1, 256) ? \
1038 ( \
1039 input_step == PSA_PAKE_STEP_KEY_SHARE ? 65 : \
1040 input_step == PSA_PAKE_STEP_ZK_PUBLIC ? 65 : \
1041 32 \
1042 ) : \
1043 0)
1044
1045 /** Output buffer size for psa_pake_output() for any of the supported PAKE
1046 * algorithm and primitive suites and output step.
1047 *
1048 * This macro must expand to a compile-time constant integer.
1049 *
1050 * The value of this macro must be at least as large as the largest value
1051 * returned by PSA_PAKE_OUTPUT_SIZE()
1052 *
1053 * See also #PSA_PAKE_OUTPUT_SIZE(\p alg, \p primitive, \p output_step).
1054 */
1055 #define PSA_PAKE_OUTPUT_MAX_SIZE 65
1056
1057 /** Input buffer size for psa_pake_input() for any of the supported PAKE
1058 * algorithm and primitive suites and input step.
1059 *
1060 * This macro must expand to a compile-time constant integer.
1061 *
1062 * The value of this macro must be at least as large as the largest value
1063 * returned by PSA_PAKE_INPUT_SIZE()
1064 *
1065 * See also #PSA_PAKE_INPUT_SIZE(\p alg, \p primitive, \p output_step).
1066 */
1067 #define PSA_PAKE_INPUT_MAX_SIZE 65
1068
1069 /** Returns a suitable initializer for a PAKE cipher suite object of type
1070 * psa_pake_cipher_suite_t.
1071 */
1072 #define PSA_PAKE_CIPHER_SUITE_INIT { PSA_ALG_NONE, 0, 0, 0, PSA_ALG_NONE }
1073
1074 /** Returns a suitable initializer for a PAKE operation object of type
1075 * psa_pake_operation_t.
1076 */
1077 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
1078 #define PSA_PAKE_OPERATION_INIT { 0 }
1079 #else
1080 #define PSA_PAKE_OPERATION_INIT { 0, PSA_ALG_NONE, 0, PSA_PAKE_OPERATION_STAGE_SETUP, \
1081 { 0 }, { { 0 } } }
1082 #endif
1083
1084 struct psa_pake_cipher_suite_s {
1085 psa_algorithm_t algorithm;
1086 psa_pake_primitive_type_t type;
1087 psa_pake_family_t family;
1088 uint16_t bits;
1089 psa_algorithm_t hash;
1090 };
1091
1092 struct psa_crypto_driver_pake_inputs_s {
1093 uint8_t *MBEDTLS_PRIVATE(password);
1094 size_t MBEDTLS_PRIVATE(password_len);
1095 uint8_t *MBEDTLS_PRIVATE(user);
1096 size_t MBEDTLS_PRIVATE(user_len);
1097 uint8_t *MBEDTLS_PRIVATE(peer);
1098 size_t MBEDTLS_PRIVATE(peer_len);
1099 psa_key_attributes_t MBEDTLS_PRIVATE(attributes);
1100 struct psa_pake_cipher_suite_s MBEDTLS_PRIVATE(cipher_suite);
1101 };
1102
1103 typedef enum psa_crypto_driver_pake_step {
1104 PSA_JPAKE_STEP_INVALID = 0, /* Invalid step */
1105 PSA_JPAKE_X1_STEP_KEY_SHARE = 1, /* Round 1: input/output key share (for ephemeral private key X1).*/
1106 PSA_JPAKE_X1_STEP_ZK_PUBLIC = 2, /* Round 1: input/output Schnorr NIZKP public key for the X1 key */
1107 PSA_JPAKE_X1_STEP_ZK_PROOF = 3, /* Round 1: input/output Schnorr NIZKP proof for the X1 key */
1108 PSA_JPAKE_X2_STEP_KEY_SHARE = 4, /* Round 1: input/output key share (for ephemeral private key X2).*/
1109 PSA_JPAKE_X2_STEP_ZK_PUBLIC = 5, /* Round 1: input/output Schnorr NIZKP public key for the X2 key */
1110 PSA_JPAKE_X2_STEP_ZK_PROOF = 6, /* Round 1: input/output Schnorr NIZKP proof for the X2 key */
1111 PSA_JPAKE_X2S_STEP_KEY_SHARE = 7, /* Round 2: output X2S key (our key) */
1112 PSA_JPAKE_X2S_STEP_ZK_PUBLIC = 8, /* Round 2: output Schnorr NIZKP public key for the X2S key (our key) */
1113 PSA_JPAKE_X2S_STEP_ZK_PROOF = 9, /* Round 2: output Schnorr NIZKP proof for the X2S key (our key) */
1114 PSA_JPAKE_X4S_STEP_KEY_SHARE = 10, /* Round 2: input X4S key (from peer) */
1115 PSA_JPAKE_X4S_STEP_ZK_PUBLIC = 11, /* Round 2: input Schnorr NIZKP public key for the X4S key (from peer) */
1116 PSA_JPAKE_X4S_STEP_ZK_PROOF = 12 /* Round 2: input Schnorr NIZKP proof for the X4S key (from peer) */
1117 } psa_crypto_driver_pake_step_t;
1118
1119 typedef enum psa_jpake_round {
1120 PSA_JPAKE_FIRST = 0,
1121 PSA_JPAKE_SECOND = 1,
1122 PSA_JPAKE_FINISHED = 2
1123 } psa_jpake_round_t;
1124
1125 typedef enum psa_jpake_io_mode {
1126 PSA_JPAKE_INPUT = 0,
1127 PSA_JPAKE_OUTPUT = 1
1128 } psa_jpake_io_mode_t;
1129
1130 struct psa_jpake_computation_stage_s {
1131 /* The J-PAKE round we are currently on */
1132 psa_jpake_round_t MBEDTLS_PRIVATE(round);
1133 /* The 'mode' we are currently in (inputting or outputting) */
1134 psa_jpake_io_mode_t MBEDTLS_PRIVATE(io_mode);
1135 /* The number of completed inputs so far this round */
1136 uint8_t MBEDTLS_PRIVATE(inputs);
1137 /* The number of completed outputs so far this round */
1138 uint8_t MBEDTLS_PRIVATE(outputs);
1139 /* The next expected step (KEY_SHARE, ZK_PUBLIC or ZK_PROOF) */
1140 psa_pake_step_t MBEDTLS_PRIVATE(step);
1141 };
1142
1143 #define PSA_JPAKE_EXPECTED_INPUTS(round) ((round) == PSA_JPAKE_FINISHED ? 0 : \
1144 ((round) == PSA_JPAKE_FIRST ? 2 : 1))
1145 #define PSA_JPAKE_EXPECTED_OUTPUTS(round) ((round) == PSA_JPAKE_FINISHED ? 0 : \
1146 ((round) == PSA_JPAKE_FIRST ? 2 : 1))
1147
1148 struct psa_pake_operation_s {
1149 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
1150 mbedtls_psa_client_handle_t handle;
1151 #else
1152 /** Unique ID indicating which driver got assigned to do the
1153 * operation. Since driver contexts are driver-specific, swapping
1154 * drivers halfway through the operation is not supported.
1155 * ID values are auto-generated in psa_crypto_driver_wrappers.h
1156 * ID value zero means the context is not valid or not assigned to
1157 * any driver (i.e. none of the driver contexts are active). */
1158 unsigned int MBEDTLS_PRIVATE(id);
1159 /* Algorithm of the PAKE operation */
1160 psa_algorithm_t MBEDTLS_PRIVATE(alg);
1161 /* A primitive of type compatible with algorithm */
1162 psa_pake_primitive_t MBEDTLS_PRIVATE(primitive);
1163 /* Stage of the PAKE operation: waiting for the setup, collecting inputs
1164 * or computing. */
1165 uint8_t MBEDTLS_PRIVATE(stage);
1166 /* Holds computation stage of the PAKE algorithms. */
1167 union {
1168 uint8_t MBEDTLS_PRIVATE(dummy);
1169 #if defined(PSA_WANT_ALG_JPAKE)
1170 struct psa_jpake_computation_stage_s MBEDTLS_PRIVATE(jpake);
1171 #endif
1172 } MBEDTLS_PRIVATE(computation_stage);
1173 union {
1174 psa_driver_pake_context_t MBEDTLS_PRIVATE(ctx);
1175 struct psa_crypto_driver_pake_inputs_s MBEDTLS_PRIVATE(inputs);
1176 } MBEDTLS_PRIVATE(data);
1177 #endif
1178 };
1179
1180 /** \addtogroup pake
1181 * @{
1182 */
1183
1184 /** The type of the data structure for PAKE cipher suites.
1185 *
1186 * This is an implementation-defined \c struct. Applications should not
1187 * make any assumptions about the content of this structure.
1188 * Implementation details can change in future versions without notice.
1189 */
1190 typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t;
1191
1192 /** Return an initial value for a PAKE cipher suite object.
1193 */
1194 static psa_pake_cipher_suite_t psa_pake_cipher_suite_init(void);
1195
1196 /** Retrieve the PAKE algorithm from a PAKE cipher suite.
1197 *
1198 * \param[in] cipher_suite The cipher suite structure to query.
1199 *
1200 * \return The PAKE algorithm stored in the cipher suite structure.
1201 */
1202 static psa_algorithm_t psa_pake_cs_get_algorithm(
1203 const psa_pake_cipher_suite_t *cipher_suite);
1204
1205 /** Declare the PAKE algorithm for the cipher suite.
1206 *
1207 * This function overwrites any PAKE algorithm
1208 * previously set in \p cipher_suite.
1209 *
1210 * \note For #PSA_ALG_JPAKE, the only supported hash algorithm is SHA-256.
1211 *
1212 * \param[out] cipher_suite The cipher suite structure to write to.
1213 * \param algorithm The PAKE algorithm to write.
1214 * (`PSA_ALG_XXX` values of type ::psa_algorithm_t
1215 * such that #PSA_ALG_IS_PAKE(\c alg) is true.)
1216 * If this is 0, the PAKE algorithm in
1217 * \p cipher_suite becomes unspecified.
1218 */
1219 static void psa_pake_cs_set_algorithm(psa_pake_cipher_suite_t *cipher_suite,
1220 psa_algorithm_t algorithm);
1221
1222 /** Retrieve the primitive from a PAKE cipher suite.
1223 *
1224 * \param[in] cipher_suite The cipher suite structure to query.
1225 *
1226 * \return The primitive stored in the cipher suite structure.
1227 */
1228 static psa_pake_primitive_t psa_pake_cs_get_primitive(
1229 const psa_pake_cipher_suite_t *cipher_suite);
1230
1231 /** Declare the primitive for a PAKE cipher suite.
1232 *
1233 * This function overwrites any primitive previously set in \p cipher_suite.
1234 *
1235 * \note For #PSA_ALG_JPAKE, the only supported primitive is ECC on the curve
1236 * secp256r1, i.e. `PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC,
1237 * PSA_ECC_FAMILY_SECP_R1, 256)`.
1238 *
1239 * \param[out] cipher_suite The cipher suite structure to write to.
1240 * \param primitive The primitive to write. If this is 0, the
1241 * primitive type in \p cipher_suite becomes
1242 * unspecified.
1243 */
1244 static void psa_pake_cs_set_primitive(psa_pake_cipher_suite_t *cipher_suite,
1245 psa_pake_primitive_t primitive);
1246
1247 /** Retrieve the PAKE family from a PAKE cipher suite.
1248 *
1249 * \param[in] cipher_suite The cipher suite structure to query.
1250 *
1251 * \return The PAKE family stored in the cipher suite structure.
1252 */
1253 static psa_pake_family_t psa_pake_cs_get_family(
1254 const psa_pake_cipher_suite_t *cipher_suite);
1255
1256 /** Retrieve the PAKE primitive bit-size from a PAKE cipher suite.
1257 *
1258 * \param[in] cipher_suite The cipher suite structure to query.
1259 *
1260 * \return The PAKE primitive bit-size stored in the cipher suite structure.
1261 */
1262 static uint16_t psa_pake_cs_get_bits(
1263 const psa_pake_cipher_suite_t *cipher_suite);
1264
1265 /** Retrieve the hash algorithm from a PAKE cipher suite.
1266 *
1267 * \param[in] cipher_suite The cipher suite structure to query.
1268 *
1269 * \return The hash algorithm stored in the cipher suite structure. The return
1270 * value is 0 if the PAKE is not parametrised by a hash algorithm or if
1271 * the hash algorithm is not set.
1272 */
1273 static psa_algorithm_t psa_pake_cs_get_hash(
1274 const psa_pake_cipher_suite_t *cipher_suite);
1275
1276 /** Declare the hash algorithm for a PAKE cipher suite.
1277 *
1278 * This function overwrites any hash algorithm
1279 * previously set in \p cipher_suite.
1280 *
1281 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
1282 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
1283 * for more information.
1284 *
1285 * \param[out] cipher_suite The cipher suite structure to write to.
1286 * \param hash The hash involved in the cipher suite.
1287 * (`PSA_ALG_XXX` values of type ::psa_algorithm_t
1288 * such that #PSA_ALG_IS_HASH(\c alg) is true.)
1289 * If this is 0, the hash algorithm in
1290 * \p cipher_suite becomes unspecified.
1291 */
1292 static void psa_pake_cs_set_hash(psa_pake_cipher_suite_t *cipher_suite,
1293 psa_algorithm_t hash);
1294
1295 /** The type of the state data structure for PAKE operations.
1296 *
1297 * Before calling any function on a PAKE operation object, the application
1298 * must initialize it by any of the following means:
1299 * - Set the structure to all-bits-zero, for example:
1300 * \code
1301 * psa_pake_operation_t operation;
1302 * memset(&operation, 0, sizeof(operation));
1303 * \endcode
1304 * - Initialize the structure to logical zero values, for example:
1305 * \code
1306 * psa_pake_operation_t operation = {0};
1307 * \endcode
1308 * - Initialize the structure to the initializer #PSA_PAKE_OPERATION_INIT,
1309 * for example:
1310 * \code
1311 * psa_pake_operation_t operation = PSA_PAKE_OPERATION_INIT;
1312 * \endcode
1313 * - Assign the result of the function psa_pake_operation_init()
1314 * to the structure, for example:
1315 * \code
1316 * psa_pake_operation_t operation;
1317 * operation = psa_pake_operation_init();
1318 * \endcode
1319 *
1320 * This is an implementation-defined \c struct. Applications should not
1321 * make any assumptions about the content of this structure.
1322 * Implementation details can change in future versions without notice. */
1323 typedef struct psa_pake_operation_s psa_pake_operation_t;
1324
1325 /** The type of input values for PAKE operations. */
1326 typedef struct psa_crypto_driver_pake_inputs_s psa_crypto_driver_pake_inputs_t;
1327
1328 /** The type of computation stage for J-PAKE operations. */
1329 typedef struct psa_jpake_computation_stage_s psa_jpake_computation_stage_t;
1330
1331 /** Return an initial value for a PAKE operation object.
1332 */
1333 static psa_pake_operation_t psa_pake_operation_init(void);
1334
1335 /** Get the length of the password in bytes from given inputs.
1336 *
1337 * \param[in] inputs Operation inputs.
1338 * \param[out] password_len Password length.
1339 *
1340 * \retval #PSA_SUCCESS
1341 * Success.
1342 * \retval #PSA_ERROR_BAD_STATE
1343 * Password hasn't been set yet.
1344 */
1345 psa_status_t psa_crypto_driver_pake_get_password_len(
1346 const psa_crypto_driver_pake_inputs_t *inputs,
1347 size_t *password_len);
1348
1349 /** Get the password from given inputs.
1350 *
1351 * \param[in] inputs Operation inputs.
1352 * \param[out] buffer Return buffer for password.
1353 * \param buffer_size Size of the return buffer in bytes.
1354 * \param[out] buffer_length Actual size of the password in bytes.
1355 *
1356 * \retval #PSA_SUCCESS
1357 * Success.
1358 * \retval #PSA_ERROR_BAD_STATE
1359 * Password hasn't been set yet.
1360 */
1361 psa_status_t psa_crypto_driver_pake_get_password(
1362 const psa_crypto_driver_pake_inputs_t *inputs,
1363 uint8_t *buffer, size_t buffer_size, size_t *buffer_length);
1364
1365 /** Get the length of the user id in bytes from given inputs.
1366 *
1367 * \param[in] inputs Operation inputs.
1368 * \param[out] user_len User id length.
1369 *
1370 * \retval #PSA_SUCCESS
1371 * Success.
1372 * \retval #PSA_ERROR_BAD_STATE
1373 * User id hasn't been set yet.
1374 */
1375 psa_status_t psa_crypto_driver_pake_get_user_len(
1376 const psa_crypto_driver_pake_inputs_t *inputs,
1377 size_t *user_len);
1378
1379 /** Get the length of the peer id in bytes from given inputs.
1380 *
1381 * \param[in] inputs Operation inputs.
1382 * \param[out] peer_len Peer id length.
1383 *
1384 * \retval #PSA_SUCCESS
1385 * Success.
1386 * \retval #PSA_ERROR_BAD_STATE
1387 * Peer id hasn't been set yet.
1388 */
1389 psa_status_t psa_crypto_driver_pake_get_peer_len(
1390 const psa_crypto_driver_pake_inputs_t *inputs,
1391 size_t *peer_len);
1392
1393 /** Get the user id from given inputs.
1394 *
1395 * \param[in] inputs Operation inputs.
1396 * \param[out] user_id User id.
1397 * \param user_id_size Size of \p user_id in bytes.
1398 * \param[out] user_id_len Size of the user id in bytes.
1399 *
1400 * \retval #PSA_SUCCESS
1401 * Success.
1402 * \retval #PSA_ERROR_BAD_STATE
1403 * User id hasn't been set yet.
1404 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1405 * The size of the \p user_id is too small.
1406 */
1407 psa_status_t psa_crypto_driver_pake_get_user(
1408 const psa_crypto_driver_pake_inputs_t *inputs,
1409 uint8_t *user_id, size_t user_id_size, size_t *user_id_len);
1410
1411 /** Get the peer id from given inputs.
1412 *
1413 * \param[in] inputs Operation inputs.
1414 * \param[out] peer_id Peer id.
1415 * \param peer_id_size Size of \p peer_id in bytes.
1416 * \param[out] peer_id_length Size of the peer id in bytes.
1417 *
1418 * \retval #PSA_SUCCESS
1419 * Success.
1420 * \retval #PSA_ERROR_BAD_STATE
1421 * Peer id hasn't been set yet.
1422 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1423 * The size of the \p peer_id is too small.
1424 */
1425 psa_status_t psa_crypto_driver_pake_get_peer(
1426 const psa_crypto_driver_pake_inputs_t *inputs,
1427 uint8_t *peer_id, size_t peer_id_size, size_t *peer_id_length);
1428
1429 /** Get the cipher suite from given inputs.
1430 *
1431 * \param[in] inputs Operation inputs.
1432 * \param[out] cipher_suite Return buffer for role.
1433 *
1434 * \retval #PSA_SUCCESS
1435 * Success.
1436 * \retval #PSA_ERROR_BAD_STATE
1437 * Cipher_suite hasn't been set yet.
1438 */
1439 psa_status_t psa_crypto_driver_pake_get_cipher_suite(
1440 const psa_crypto_driver_pake_inputs_t *inputs,
1441 psa_pake_cipher_suite_t *cipher_suite);
1442
1443 /** Set the session information for a password-authenticated key exchange.
1444 *
1445 * The sequence of operations to set up a password-authenticated key exchange
1446 * is as follows:
1447 * -# Allocate an operation object which will be passed to all the functions
1448 * listed here.
1449 * -# Initialize the operation object with one of the methods described in the
1450 * documentation for #psa_pake_operation_t, e.g.
1451 * #PSA_PAKE_OPERATION_INIT.
1452 * -# Call psa_pake_setup() to specify the cipher suite.
1453 * -# Call \c psa_pake_set_xxx() functions on the operation to complete the
1454 * setup. The exact sequence of \c psa_pake_set_xxx() functions that needs
1455 * to be called depends on the algorithm in use.
1456 *
1457 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
1458 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
1459 * for more information.
1460 *
1461 * A typical sequence of calls to perform a password-authenticated key
1462 * exchange:
1463 * -# Call psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to get the
1464 * key share that needs to be sent to the peer.
1465 * -# Call psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to provide
1466 * the key share that was received from the peer.
1467 * -# Depending on the algorithm additional calls to psa_pake_output() and
1468 * psa_pake_input() might be necessary.
1469 * -# Call psa_pake_get_implicit_key() for accessing the shared secret.
1470 *
1471 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
1472 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
1473 * for more information.
1474 *
1475 * If an error occurs at any step after a call to psa_pake_setup(),
1476 * the operation will need to be reset by a call to psa_pake_abort(). The
1477 * application may call psa_pake_abort() at any time after the operation
1478 * has been initialized.
1479 *
1480 * After a successful call to psa_pake_setup(), the application must
1481 * eventually terminate the operation. The following events terminate an
1482 * operation:
1483 * - A call to psa_pake_abort().
1484 * - A successful call to psa_pake_get_implicit_key().
1485 *
1486 * \param[in,out] operation The operation object to set up. It must have
1487 * been initialized but not set up yet.
1488 * \param[in] cipher_suite The cipher suite to use. (A cipher suite fully
1489 * characterizes a PAKE algorithm and determines
1490 * the algorithm as well.)
1491 *
1492 * \retval #PSA_SUCCESS
1493 * Success.
1494 * \retval #PSA_ERROR_INVALID_ARGUMENT
1495 * The algorithm in \p cipher_suite is not a PAKE algorithm, or the
1496 * PAKE primitive in \p cipher_suite is not compatible with the
1497 * PAKE algorithm, or the hash algorithm in \p cipher_suite is invalid
1498 * or not compatible with the PAKE algorithm and primitive.
1499 * \retval #PSA_ERROR_NOT_SUPPORTED
1500 * The algorithm in \p cipher_suite is not a supported PAKE algorithm,
1501 * or the PAKE primitive in \p cipher_suite is not supported or not
1502 * compatible with the PAKE algorithm, or the hash algorithm in
1503 * \p cipher_suite is not supported or not compatible with the PAKE
1504 * algorithm and primitive.
1505 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1506 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1507 * \retval #PSA_ERROR_BAD_STATE
1508 * The operation state is not valid, or
1509 * the library has not been previously initialized by psa_crypto_init().
1510 * It is implementation-dependent whether a failure to initialize
1511 * results in this error code.
1512 */
1513 psa_status_t psa_pake_setup(psa_pake_operation_t *operation,
1514 const psa_pake_cipher_suite_t *cipher_suite);
1515
1516 /** Set the password for a password-authenticated key exchange from key ID.
1517 *
1518 * Call this function when the password, or a value derived from the password,
1519 * is already present in the key store.
1520 *
1521 * \param[in,out] operation The operation object to set the password for. It
1522 * must have been set up by psa_pake_setup() and
1523 * not yet in use (neither psa_pake_output() nor
1524 * psa_pake_input() has been called yet). It must
1525 * be on operation for which the password hasn't
1526 * been set yet (psa_pake_set_password_key()
1527 * hasn't been called yet).
1528 * \param password Identifier of the key holding the password or a
1529 * value derived from the password (eg. by a
1530 * memory-hard function). It must remain valid
1531 * until the operation terminates. It must be of
1532 * type #PSA_KEY_TYPE_PASSWORD or
1533 * #PSA_KEY_TYPE_PASSWORD_HASH. It has to allow
1534 * the usage #PSA_KEY_USAGE_DERIVE.
1535 *
1536 * \retval #PSA_SUCCESS
1537 * Success.
1538 * \retval #PSA_ERROR_INVALID_HANDLE
1539 * \p password is not a valid key identifier.
1540 * \retval #PSA_ERROR_NOT_PERMITTED
1541 * The key does not have the #PSA_KEY_USAGE_DERIVE flag, or it does not
1542 * permit the \p operation's algorithm.
1543 * \retval #PSA_ERROR_INVALID_ARGUMENT
1544 * The key type for \p password is not #PSA_KEY_TYPE_PASSWORD or
1545 * #PSA_KEY_TYPE_PASSWORD_HASH, or \p password is not compatible with
1546 * the \p operation's cipher suite.
1547 * \retval #PSA_ERROR_NOT_SUPPORTED
1548 * The key type or key size of \p password is not supported with the
1549 * \p operation's cipher suite.
1550 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1551 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1552 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
1553 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
1554 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
1555 * \retval #PSA_ERROR_BAD_STATE
1556 * The operation state is not valid (it must have been set up.), or
1557 * the library has not been previously initialized by psa_crypto_init().
1558 * It is implementation-dependent whether a failure to initialize
1559 * results in this error code.
1560 */
1561 psa_status_t psa_pake_set_password_key(psa_pake_operation_t *operation,
1562 mbedtls_svc_key_id_t password);
1563
1564 /** Set the user ID for a password-authenticated key exchange.
1565 *
1566 * Call this function to set the user ID. For PAKE algorithms that associate a
1567 * user identifier with each side of the session you need to call
1568 * psa_pake_set_peer() as well. For PAKE algorithms that associate a single
1569 * user identifier with the session, call psa_pake_set_user() only.
1570 *
1571 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
1572 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
1573 * for more information.
1574 *
1575 * \note When using the built-in implementation of #PSA_ALG_JPAKE, the user ID
1576 * must be `"client"` (6-byte string) or `"server"` (6-byte string).
1577 * Third-party drivers may or may not have this limitation.
1578 *
1579 * \param[in,out] operation The operation object to set the user ID for. It
1580 * must have been set up by psa_pake_setup() and
1581 * not yet in use (neither psa_pake_output() nor
1582 * psa_pake_input() has been called yet). It must
1583 * be on operation for which the user ID hasn't
1584 * been set (psa_pake_set_user() hasn't been
1585 * called yet).
1586 * \param[in] user_id The user ID to authenticate with.
1587 * \param user_id_len Size of the \p user_id buffer in bytes.
1588 *
1589 * \retval #PSA_SUCCESS
1590 * Success.
1591 * \retval #PSA_ERROR_INVALID_ARGUMENT
1592 * \p user_id is not valid for the \p operation's algorithm and cipher
1593 * suite.
1594 * \retval #PSA_ERROR_NOT_SUPPORTED
1595 * The value of \p user_id is not supported by the implementation.
1596 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
1597 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1598 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1599 * \retval #PSA_ERROR_BAD_STATE
1600 * The operation state is not valid, or
1601 * the library has not been previously initialized by psa_crypto_init().
1602 * It is implementation-dependent whether a failure to initialize
1603 * results in this error code.
1604 */
1605 psa_status_t psa_pake_set_user(psa_pake_operation_t *operation,
1606 const uint8_t *user_id,
1607 size_t user_id_len);
1608
1609 /** Set the peer ID for a password-authenticated key exchange.
1610 *
1611 * Call this function in addition to psa_pake_set_user() for PAKE algorithms
1612 * that associate a user identifier with each side of the session. For PAKE
1613 * algorithms that associate a single user identifier with the session, call
1614 * psa_pake_set_user() only.
1615 *
1616 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
1617 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
1618 * for more information.
1619 *
1620 * \note When using the built-in implementation of #PSA_ALG_JPAKE, the peer ID
1621 * must be `"client"` (6-byte string) or `"server"` (6-byte string).
1622 * Third-party drivers may or may not have this limitation.
1623 *
1624 * \param[in,out] operation The operation object to set the peer ID for. It
1625 * must have been set up by psa_pake_setup() and
1626 * not yet in use (neither psa_pake_output() nor
1627 * psa_pake_input() has been called yet). It must
1628 * be on operation for which the peer ID hasn't
1629 * been set (psa_pake_set_peer() hasn't been
1630 * called yet).
1631 * \param[in] peer_id The peer's ID to authenticate.
1632 * \param peer_id_len Size of the \p peer_id buffer in bytes.
1633 *
1634 * \retval #PSA_SUCCESS
1635 * Success.
1636 * \retval #PSA_ERROR_INVALID_ARGUMENT
1637 * \p peer_id is not valid for the \p operation's algorithm and cipher
1638 * suite.
1639 * \retval #PSA_ERROR_NOT_SUPPORTED
1640 * The algorithm doesn't associate a second identity with the session.
1641 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
1642 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1643 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1644 * \retval #PSA_ERROR_BAD_STATE
1645 * Calling psa_pake_set_peer() is invalid with the \p operation's
1646 * algorithm, the operation state is not valid, or the library has not
1647 * been previously initialized by psa_crypto_init().
1648 * It is implementation-dependent whether a failure to initialize
1649 * results in this error code.
1650 */
1651 psa_status_t psa_pake_set_peer(psa_pake_operation_t *operation,
1652 const uint8_t *peer_id,
1653 size_t peer_id_len);
1654
1655 /** Set the application role for a password-authenticated key exchange.
1656 *
1657 * Not all PAKE algorithms need to differentiate the communicating entities.
1658 * It is optional to call this function for PAKEs that don't require a role
1659 * to be specified. For such PAKEs the application role parameter is ignored,
1660 * or #PSA_PAKE_ROLE_NONE can be passed as \c role.
1661 *
1662 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
1663 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
1664 * for more information.
1665 *
1666 * \param[in,out] operation The operation object to specify the
1667 * application's role for. It must have been set up
1668 * by psa_pake_setup() and not yet in use (neither
1669 * psa_pake_output() nor psa_pake_input() has been
1670 * called yet). It must be on operation for which
1671 * the application's role hasn't been specified
1672 * (psa_pake_set_role() hasn't been called yet).
1673 * \param role A value of type ::psa_pake_role_t indicating the
1674 * application's role in the PAKE the algorithm
1675 * that is being set up. For more information see
1676 * the documentation of \c PSA_PAKE_ROLE_XXX
1677 * constants.
1678 *
1679 * \retval #PSA_SUCCESS
1680 * Success.
1681 * \retval #PSA_ERROR_INVALID_ARGUMENT
1682 * The \p role is not a valid PAKE role in the \p operation’s algorithm.
1683 * \retval #PSA_ERROR_NOT_SUPPORTED
1684 * The \p role for this algorithm is not supported or is not valid.
1685 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1686 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1687 * \retval #PSA_ERROR_BAD_STATE
1688 * The operation state is not valid, or
1689 * the library has not been previously initialized by psa_crypto_init().
1690 * It is implementation-dependent whether a failure to initialize
1691 * results in this error code.
1692 */
1693 psa_status_t psa_pake_set_role(psa_pake_operation_t *operation,
1694 psa_pake_role_t role);
1695
1696 /** Get output for a step of a password-authenticated key exchange.
1697 *
1698 * Depending on the algorithm being executed, you might need to call this
1699 * function several times or you might not need to call this at all.
1700 *
1701 * The exact sequence of calls to perform a password-authenticated key
1702 * exchange depends on the algorithm in use. Refer to the documentation of
1703 * individual PAKE algorithm types (`PSA_ALG_XXX` values of type
1704 * ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
1705 * information.
1706 *
1707 * If this function returns an error status, the operation enters an error
1708 * state and must be aborted by calling psa_pake_abort().
1709 *
1710 * \param[in,out] operation Active PAKE operation.
1711 * \param step The step of the algorithm for which the output is
1712 * requested.
1713 * \param[out] output Buffer where the output is to be written in the
1714 * format appropriate for this \p step. Refer to
1715 * the documentation of the individual
1716 * \c PSA_PAKE_STEP_XXX constants for more
1717 * information.
1718 * \param output_size Size of the \p output buffer in bytes. This must
1719 * be at least #PSA_PAKE_OUTPUT_SIZE(\c alg, \c
1720 * primitive, \p output_step) where \c alg and
1721 * \p primitive are the PAKE algorithm and primitive
1722 * in the operation's cipher suite, and \p step is
1723 * the output step.
1724 *
1725 * \param[out] output_length On success, the number of bytes of the returned
1726 * output.
1727 *
1728 * \retval #PSA_SUCCESS
1729 * Success.
1730 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1731 * The size of the \p output buffer is too small.
1732 * \retval #PSA_ERROR_INVALID_ARGUMENT
1733 * \p step is not compatible with the operation's algorithm.
1734 * \retval #PSA_ERROR_NOT_SUPPORTED
1735 * \p step is not supported with the operation's algorithm.
1736 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription
1737 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
1738 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1739 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1740 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
1741 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
1742 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
1743 * \retval #PSA_ERROR_BAD_STATE
1744 * The operation state is not valid (it must be active, and fully set
1745 * up, and this call must conform to the algorithm's requirements
1746 * for ordering of input and output steps), or
1747 * the library has not been previously initialized by psa_crypto_init().
1748 * It is implementation-dependent whether a failure to initialize
1749 * results in this error code.
1750 */
1751 psa_status_t psa_pake_output(psa_pake_operation_t *operation,
1752 psa_pake_step_t step,
1753 uint8_t *output,
1754 size_t output_size,
1755 size_t *output_length);
1756
1757 /** Provide input for a step of a password-authenticated key exchange.
1758 *
1759 * Depending on the algorithm being executed, you might need to call this
1760 * function several times or you might not need to call this at all.
1761 *
1762 * The exact sequence of calls to perform a password-authenticated key
1763 * exchange depends on the algorithm in use. Refer to the documentation of
1764 * individual PAKE algorithm types (`PSA_ALG_XXX` values of type
1765 * ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
1766 * information.
1767 *
1768 * If this function returns an error status, the operation enters an error
1769 * state and must be aborted by calling psa_pake_abort().
1770 *
1771 * \param[in,out] operation Active PAKE operation.
1772 * \param step The step for which the input is provided.
1773 * \param[in] input Buffer containing the input in the format
1774 * appropriate for this \p step. Refer to the
1775 * documentation of the individual
1776 * \c PSA_PAKE_STEP_XXX constants for more
1777 * information.
1778 * \param input_length Size of the \p input buffer in bytes.
1779 *
1780 * \retval #PSA_SUCCESS
1781 * Success.
1782 * \retval #PSA_ERROR_INVALID_SIGNATURE
1783 * The verification fails for a #PSA_PAKE_STEP_ZK_PROOF input step.
1784 * \retval #PSA_ERROR_INVALID_ARGUMENT
1785 * \p input_length is not compatible with the \p operation’s algorithm,
1786 * or the \p input is not valid for the \p operation's algorithm,
1787 * cipher suite or \p step.
1788 * \retval #PSA_ERROR_NOT_SUPPORTED
1789 * \p step p is not supported with the \p operation's algorithm, or the
1790 * \p input is not supported for the \p operation's algorithm, cipher
1791 * suite or \p step.
1792 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
1793 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1794 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1795 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
1796 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
1797 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
1798 * \retval #PSA_ERROR_BAD_STATE
1799 * The operation state is not valid (it must be active, and fully set
1800 * up, and this call must conform to the algorithm's requirements
1801 * for ordering of input and output steps), or
1802 * the library has not been previously initialized by psa_crypto_init().
1803 * It is implementation-dependent whether a failure to initialize
1804 * results in this error code.
1805 */
1806 psa_status_t psa_pake_input(psa_pake_operation_t *operation,
1807 psa_pake_step_t step,
1808 const uint8_t *input,
1809 size_t input_length);
1810
1811 /** Get implicitly confirmed shared secret from a PAKE.
1812 *
1813 * At this point there is a cryptographic guarantee that only the authenticated
1814 * party who used the same password is able to compute the key. But there is no
1815 * guarantee that the peer is the party it claims to be and was able to do so.
1816 *
1817 * That is, the authentication is only implicit. Since the peer is not
1818 * authenticated yet, no action should be taken yet that assumes that the peer
1819 * is who it claims to be. For example, do not access restricted files on the
1820 * peer's behalf until an explicit authentication has succeeded.
1821 *
1822 * This function can be called after the key exchange phase of the operation
1823 * has completed. It imports the shared secret output of the PAKE into the
1824 * provided derivation operation. The input step
1825 * #PSA_KEY_DERIVATION_INPUT_SECRET is used when placing the shared key
1826 * material in the key derivation operation.
1827 *
1828 * The exact sequence of calls to perform a password-authenticated key
1829 * exchange depends on the algorithm in use. Refer to the documentation of
1830 * individual PAKE algorithm types (`PSA_ALG_XXX` values of type
1831 * ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
1832 * information.
1833 *
1834 * When this function returns successfully, \p operation becomes inactive.
1835 * If this function returns an error status, both \p operation
1836 * and \c key_derivation operations enter an error state and must be aborted by
1837 * calling psa_pake_abort() and psa_key_derivation_abort() respectively.
1838 *
1839 * \param[in,out] operation Active PAKE operation.
1840 * \param[out] output A key derivation operation that is ready
1841 * for an input step of type
1842 * #PSA_KEY_DERIVATION_INPUT_SECRET.
1843 *
1844 * \retval #PSA_SUCCESS
1845 * Success.
1846 * \retval #PSA_ERROR_INVALID_ARGUMENT
1847 * #PSA_KEY_DERIVATION_INPUT_SECRET is not compatible with the
1848 * algorithm in the \p output key derivation operation.
1849 * \retval #PSA_ERROR_NOT_SUPPORTED
1850 * Input from a PAKE is not supported by the algorithm in the \p output
1851 * key derivation operation.
1852 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
1853 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1854 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1855 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
1856 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
1857 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
1858 * \retval #PSA_ERROR_BAD_STATE
1859 * The PAKE operation state is not valid (it must be active, but beyond
1860 * that validity is specific to the algorithm), or
1861 * the library has not been previously initialized by psa_crypto_init(),
1862 * or the state of \p output is not valid for
1863 * the #PSA_KEY_DERIVATION_INPUT_SECRET step. This can happen if the
1864 * step is out of order or the application has done this step already
1865 * and it may not be repeated.
1866 * It is implementation-dependent whether a failure to initialize
1867 * results in this error code.
1868 */
1869 psa_status_t psa_pake_get_implicit_key(psa_pake_operation_t *operation,
1870 psa_key_derivation_operation_t *output);
1871
1872 /** Abort a PAKE operation.
1873 *
1874 * Aborting an operation frees all associated resources except for the \c
1875 * operation structure itself. Once aborted, the operation object can be reused
1876 * for another operation by calling psa_pake_setup() again.
1877 *
1878 * This function may be called at any time after the operation
1879 * object has been initialized as described in #psa_pake_operation_t.
1880 *
1881 * In particular, calling psa_pake_abort() after the operation has been
1882 * terminated by a call to psa_pake_abort() or psa_pake_get_implicit_key()
1883 * is safe and has no effect.
1884 *
1885 * \param[in,out] operation The operation to abort.
1886 *
1887 * \retval #PSA_SUCCESS
1888 * Success.
1889 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1890 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1891 * \retval #PSA_ERROR_BAD_STATE
1892 * The library has not been previously initialized by psa_crypto_init().
1893 * It is implementation-dependent whether a failure to initialize
1894 * results in this error code.
1895 */
1896 psa_status_t psa_pake_abort(psa_pake_operation_t *operation);
1897
1898 /**@}*/
1899
psa_pake_cs_get_algorithm(const psa_pake_cipher_suite_t * cipher_suite)1900 static inline psa_algorithm_t psa_pake_cs_get_algorithm(
1901 const psa_pake_cipher_suite_t *cipher_suite)
1902 {
1903 return cipher_suite->algorithm;
1904 }
1905
psa_pake_cs_set_algorithm(psa_pake_cipher_suite_t * cipher_suite,psa_algorithm_t algorithm)1906 static inline void psa_pake_cs_set_algorithm(
1907 psa_pake_cipher_suite_t *cipher_suite,
1908 psa_algorithm_t algorithm)
1909 {
1910 if (!PSA_ALG_IS_PAKE(algorithm)) {
1911 cipher_suite->algorithm = 0;
1912 } else {
1913 cipher_suite->algorithm = algorithm;
1914 }
1915 }
1916
psa_pake_cs_get_primitive(const psa_pake_cipher_suite_t * cipher_suite)1917 static inline psa_pake_primitive_t psa_pake_cs_get_primitive(
1918 const psa_pake_cipher_suite_t *cipher_suite)
1919 {
1920 return PSA_PAKE_PRIMITIVE(cipher_suite->type, cipher_suite->family,
1921 cipher_suite->bits);
1922 }
1923
psa_pake_cs_set_primitive(psa_pake_cipher_suite_t * cipher_suite,psa_pake_primitive_t primitive)1924 static inline void psa_pake_cs_set_primitive(
1925 psa_pake_cipher_suite_t *cipher_suite,
1926 psa_pake_primitive_t primitive)
1927 {
1928 cipher_suite->type = (psa_pake_primitive_type_t) (primitive >> 24);
1929 cipher_suite->family = (psa_pake_family_t) (0xFF & (primitive >> 16));
1930 cipher_suite->bits = (uint16_t) (0xFFFF & primitive);
1931 }
1932
psa_pake_cs_get_family(const psa_pake_cipher_suite_t * cipher_suite)1933 static inline psa_pake_family_t psa_pake_cs_get_family(
1934 const psa_pake_cipher_suite_t *cipher_suite)
1935 {
1936 return cipher_suite->family;
1937 }
1938
psa_pake_cs_get_bits(const psa_pake_cipher_suite_t * cipher_suite)1939 static inline uint16_t psa_pake_cs_get_bits(
1940 const psa_pake_cipher_suite_t *cipher_suite)
1941 {
1942 return cipher_suite->bits;
1943 }
1944
psa_pake_cs_get_hash(const psa_pake_cipher_suite_t * cipher_suite)1945 static inline psa_algorithm_t psa_pake_cs_get_hash(
1946 const psa_pake_cipher_suite_t *cipher_suite)
1947 {
1948 return cipher_suite->hash;
1949 }
1950
psa_pake_cs_set_hash(psa_pake_cipher_suite_t * cipher_suite,psa_algorithm_t hash)1951 static inline void psa_pake_cs_set_hash(psa_pake_cipher_suite_t *cipher_suite,
1952 psa_algorithm_t hash)
1953 {
1954 if (!PSA_ALG_IS_HASH(hash)) {
1955 cipher_suite->hash = 0;
1956 } else {
1957 cipher_suite->hash = hash;
1958 }
1959 }
1960
psa_pake_cipher_suite_init(void)1961 static inline struct psa_pake_cipher_suite_s psa_pake_cipher_suite_init(void)
1962 {
1963 const struct psa_pake_cipher_suite_s v = PSA_PAKE_CIPHER_SUITE_INIT;
1964 return v;
1965 }
1966
psa_pake_operation_init(void)1967 static inline struct psa_pake_operation_s psa_pake_operation_init(void)
1968 {
1969 const struct psa_pake_operation_s v = PSA_PAKE_OPERATION_INIT;
1970 return v;
1971 }
1972
1973 #ifdef __cplusplus
1974 }
1975 #endif
1976
1977 #endif /* PSA_CRYPTO_EXTRA_H */
1978