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