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