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