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