Coverage Report

Created: 2024-11-21 07:03

/src/mbedtls/include/psa/crypto_extra.h
Line
Count
Source (jump to first uncovered line)
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
45
#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
static inline void psa_set_key_enrollment_algorithm(
69
    psa_key_attributes_t *attributes,
70
    psa_algorithm_t alg2)
71
0
{
72
0
    attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg2) = alg2;
73
0
}
Unexecuted instantiation: module.cpp:psa_set_key_enrollment_algorithm(psa_key_attributes_s*, unsigned int)
Unexecuted instantiation: psa_crypto.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_aead.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_cipher.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_client.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_ecp.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_ffdh.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_hash.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_mac.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_pake.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_rsa.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_slot_management.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_storage.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: psa_util.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: rsa.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: md.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: oid.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: pkcs12.c:psa_set_key_enrollment_algorithm
Unexecuted instantiation: pkcs5.c:psa_set_key_enrollment_algorithm
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
0
{
84
0
    return attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg2);
85
0
}
Unexecuted instantiation: module.cpp:psa_get_key_enrollment_algorithm(psa_key_attributes_s const*)
Unexecuted instantiation: psa_crypto.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_aead.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_cipher.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_client.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_ecp.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_ffdh.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_hash.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_mac.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_pake.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_rsa.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_slot_management.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: psa_crypto_storage.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: psa_util.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: rsa.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: md.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: oid.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: pkcs12.c:psa_get_key_enrollment_algorithm
Unexecuted instantiation: pkcs5.c:psa_get_key_enrollment_algorithm
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
0
#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
0
#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
658
#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
658
#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
658
    (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) ==  \
408
658
     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
658
    PSA_ALG_IS_DSA(alg)
422
423
/**@}*/
424
425
/** \addtogroup attributes
426
 * @{
427
 */
428
429
/** PAKE operation stages. */
430
0
#define PSA_PAKE_OPERATION_STAGE_SETUP 0
431
0
#define PSA_PAKE_OPERATION_STAGE_COLLECT_INPUTS 1
432
0
#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
1.50k
#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
/** \addtogroup crypto_types
587
 * @{
588
 */
589
590
0
#define PSA_ALG_CATEGORY_PAKE                   ((psa_algorithm_t) 0x0a000000)
591
592
/** Whether the specified algorithm is a password-authenticated key exchange.
593
 *
594
 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
595
 *
596
 * \return 1 if \p alg is a password-authenticated key exchange (PAKE)
597
 *         algorithm, 0 otherwise.
598
 *         This macro may return either 0 or 1 if \p alg is not a supported
599
 *         algorithm identifier.
600
 */
601
#define PSA_ALG_IS_PAKE(alg)                                        \
602
0
    (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_PAKE)
603
604
/** The Password-authenticated key exchange by juggling (J-PAKE) algorithm.
605
 *
606
 * This is J-PAKE as defined by RFC 8236, instantiated with the following
607
 * parameters:
608
 *
609
 * - The group can be either an elliptic curve or defined over a finite field.
610
 * - Schnorr NIZK proof as defined by RFC 8235 and using the same group as the
611
 *   J-PAKE algorithm.
612
 * - A cryptographic hash function.
613
 *
614
 * To select these parameters and set up the cipher suite, call these functions
615
 * in any order:
616
 *
617
 * \code
618
 * psa_pake_cs_set_algorithm(cipher_suite, PSA_ALG_JPAKE);
619
 * psa_pake_cs_set_primitive(cipher_suite,
620
 *                           PSA_PAKE_PRIMITIVE(type, family, bits));
621
 * psa_pake_cs_set_hash(cipher_suite, hash);
622
 * \endcode
623
 *
624
 * For more information on how to set a specific curve or field, refer to the
625
 * documentation of the individual \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
626
 *
627
 * After initializing a J-PAKE operation, call
628
 *
629
 * \code
630
 * psa_pake_setup(operation, cipher_suite);
631
 * psa_pake_set_user(operation, ...);
632
 * psa_pake_set_peer(operation, ...);
633
 * psa_pake_set_password_key(operation, ...);
634
 * \endcode
635
 *
636
 * The password is provided as a key. This can be the password text itself,
637
 * in an agreed character encoding, or some value derived from the password
638
 * as required by a higher level protocol.
639
 *
640
 * (The implementation converts the key material to a number as described in
641
 * Section 2.3.8 of _SEC 1: Elliptic Curve Cryptography_
642
 * (https://www.secg.org/sec1-v2.pdf), before reducing it modulo \c q. Here
643
 * \c q is order of the group defined by the primitive set in the cipher suite.
644
 * The \c psa_pake_set_password_key() function returns an error if the result
645
 * of the reduction is 0.)
646
 *
647
 * The key exchange flow for J-PAKE is as follows:
648
 * -# To get the first round data that needs to be sent to the peer, call
649
 *    \code
650
 *    // Get g1
651
 *    psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
652
 *    // Get the ZKP public key for x1
653
 *    psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
654
 *    // Get the ZKP proof for x1
655
 *    psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
656
 *    // Get g2
657
 *    psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
658
 *    // Get the ZKP public key for x2
659
 *    psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
660
 *    // Get the ZKP proof for x2
661
 *    psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
662
 *    \endcode
663
 * -# To provide the first round data received from the peer to the operation,
664
 *    call
665
 *    \code
666
 *    // Set g3
667
 *    psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
668
 *    // Set the ZKP public key for x3
669
 *    psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
670
 *    // Set the ZKP proof for x3
671
 *    psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
672
 *    // Set g4
673
 *    psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
674
 *    // Set the ZKP public key for x4
675
 *    psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
676
 *    // Set the ZKP proof for x4
677
 *    psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
678
 *    \endcode
679
 * -# To get the second round data that needs to be sent to the peer, call
680
 *    \code
681
 *    // Get A
682
 *    psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
683
 *    // Get ZKP public key for x2*s
684
 *    psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
685
 *    // Get ZKP proof for x2*s
686
 *    psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
687
 *    \endcode
688
 * -# To provide the second round data received from the peer to the operation,
689
 *    call
690
 *    \code
691
 *    // Set B
692
 *    psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
693
 *    // Set ZKP public key for x4*s
694
 *    psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
695
 *    // Set ZKP proof for x4*s
696
 *    psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
697
 *    \endcode
698
 * -# To access the shared secret call
699
 *    \code
700
 *    // Get Ka=Kb=K
701
 *    psa_pake_get_implicit_key()
702
 *    \endcode
703
 *
704
 * For more information consult the documentation of the individual
705
 * \c PSA_PAKE_STEP_XXX constants.
706
 *
707
 * At this point there is a cryptographic guarantee that only the authenticated
708
 * party who used the same password is able to compute the key. But there is no
709
 * guarantee that the peer is the party it claims to be and was able to do so.
710
 *
711
 * That is, the authentication is only implicit (the peer is not authenticated
712
 * at this point, and no action should be taken that assume that they are - like
713
 * for example accessing restricted files).
714
 *
715
 * To make the authentication explicit there are various methods, see Section 5
716
 * of RFC 8236 for two examples.
717
 *
718
 */
719
0
#define PSA_ALG_JPAKE                   ((psa_algorithm_t) 0x0a000100)
720
721
/** @} */
722
723
/** \defgroup pake Password-authenticated key exchange (PAKE)
724
 *
725
 * This is a proposed PAKE interface for the PSA Crypto API. It is not part of
726
 * the official PSA Crypto API yet.
727
 *
728
 * \note The content of this section is not part of the stable API and ABI
729
 *       of Mbed TLS and may change arbitrarily from version to version.
730
 *       Same holds for the corresponding macros #PSA_ALG_CATEGORY_PAKE and
731
 *       #PSA_ALG_JPAKE.
732
 * @{
733
 */
734
735
/** \brief Encoding of the application role of PAKE
736
 *
737
 * Encodes the application's role in the algorithm is being executed. For more
738
 * information see the documentation of individual \c PSA_PAKE_ROLE_XXX
739
 * constants.
740
 */
741
typedef uint8_t psa_pake_role_t;
742
743
/** Encoding of input and output indicators for PAKE.
744
 *
745
 * Some PAKE algorithms need to exchange more data than just a single key share.
746
 * This type is for encoding additional input and output data for such
747
 * algorithms.
748
 */
749
typedef uint8_t psa_pake_step_t;
750
751
/** Encoding of the type of the PAKE's primitive.
752
 *
753
 * Values defined by this standard will never be in the range 0x80-0xff.
754
 * Vendors who define additional types must use an encoding in this range.
755
 *
756
 * For more information see the documentation of individual
757
 * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
758
 */
759
typedef uint8_t psa_pake_primitive_type_t;
760
761
/** \brief Encoding of the family of the primitive associated with the PAKE.
762
 *
763
 * For more information see the documentation of individual
764
 * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
765
 */
766
typedef uint8_t psa_pake_family_t;
767
768
/** \brief Encoding of the primitive associated with the PAKE.
769
 *
770
 * For more information see the documentation of the #PSA_PAKE_PRIMITIVE macro.
771
 */
772
typedef uint32_t psa_pake_primitive_t;
773
774
/** A value to indicate no role in a PAKE algorithm.
775
 * This value can be used in a call to psa_pake_set_role() for symmetric PAKE
776
 * algorithms which do not assign roles.
777
 */
778
0
#define PSA_PAKE_ROLE_NONE                  ((psa_pake_role_t) 0x00)
779
780
/** The first peer in a balanced PAKE.
781
 *
782
 * Although balanced PAKE algorithms are symmetric, some of them needs an
783
 * ordering of peers for the transcript calculations. If the algorithm does not
784
 * need this, both #PSA_PAKE_ROLE_FIRST and #PSA_PAKE_ROLE_SECOND are
785
 * accepted.
786
 */
787
#define PSA_PAKE_ROLE_FIRST                ((psa_pake_role_t) 0x01)
788
789
/** The second peer in a balanced PAKE.
790
 *
791
 * Although balanced PAKE algorithms are symmetric, some of them needs an
792
 * ordering of peers for the transcript calculations. If the algorithm does not
793
 * need this, either #PSA_PAKE_ROLE_FIRST or #PSA_PAKE_ROLE_SECOND are
794
 * accepted.
795
 */
796
#define PSA_PAKE_ROLE_SECOND                ((psa_pake_role_t) 0x02)
797
798
/** The client in an augmented PAKE.
799
 *
800
 * Augmented PAKE algorithms need to differentiate between client and server.
801
 */
802
#define PSA_PAKE_ROLE_CLIENT                ((psa_pake_role_t) 0x11)
803
804
/** The server in an augmented PAKE.
805
 *
806
 * Augmented PAKE algorithms need to differentiate between client and server.
807
 */
808
#define PSA_PAKE_ROLE_SERVER                ((psa_pake_role_t) 0x12)
809
810
/** The PAKE primitive type indicating the use of elliptic curves.
811
 *
812
 * The values of the \c family and \c bits fields of the cipher suite identify a
813
 * specific elliptic curve, using the same mapping that is used for ECC
814
 * (::psa_ecc_family_t) keys.
815
 *
816
 * (Here \c family means the value returned by psa_pake_cs_get_family() and
817
 * \c bits means the value returned by psa_pake_cs_get_bits().)
818
 *
819
 * Input and output during the operation can involve group elements and scalar
820
 * values:
821
 * -# The format for group elements is the same as for public keys on the
822
 *  specific curve would be. For more information, consult the documentation of
823
 *  psa_export_public_key().
824
 * -# The format for scalars is the same as for private keys on the specific
825
 *  curve would be. For more information, consult the documentation of
826
 *  psa_export_key().
827
 */
828
0
#define PSA_PAKE_PRIMITIVE_TYPE_ECC       ((psa_pake_primitive_type_t) 0x01)
829
830
/** The PAKE primitive type indicating the use of Diffie-Hellman groups.
831
 *
832
 * The values of the \c family and \c bits fields of the cipher suite identify
833
 * a specific Diffie-Hellman group, using the same mapping that is used for
834
 * Diffie-Hellman (::psa_dh_family_t) keys.
835
 *
836
 * (Here \c family means the value returned by psa_pake_cs_get_family() and
837
 * \c bits means the value returned by psa_pake_cs_get_bits().)
838
 *
839
 * Input and output during the operation can involve group elements and scalar
840
 * values:
841
 * -# The format for group elements is the same as for public keys on the
842
 *  specific group would be. For more information, consult the documentation of
843
 *  psa_export_public_key().
844
 * -# The format for scalars is the same as for private keys on the specific
845
 *  group would be. For more information, consult the documentation of
846
 *  psa_export_key().
847
 */
848
#define PSA_PAKE_PRIMITIVE_TYPE_DH       ((psa_pake_primitive_type_t) 0x02)
849
850
/** Construct a PAKE primitive from type, family and bit-size.
851
 *
852
 * \param pake_type     The type of the primitive
853
 *                      (value of type ::psa_pake_primitive_type_t).
854
 * \param pake_family   The family of the primitive
855
 *                      (the type and interpretation of this parameter depends
856
 *                      on \p pake_type, for more information consult the
857
 *                      documentation of individual ::psa_pake_primitive_type_t
858
 *                      constants).
859
 * \param pake_bits     The bit-size of the primitive
860
 *                      (Value of type \c size_t. The interpretation
861
 *                      of this parameter depends on \p pake_family, for more
862
 *                      information consult the documentation of individual
863
 *                      ::psa_pake_primitive_type_t constants).
864
 *
865
 * \return The constructed primitive value of type ::psa_pake_primitive_t.
866
 *         Return 0 if the requested primitive can't be encoded as
867
 *         ::psa_pake_primitive_t.
868
 */
869
#define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits) \
870
0
    ((pake_bits & 0xFFFF) != pake_bits) ? 0 :                 \
871
0
    ((psa_pake_primitive_t) (((pake_type) << 24 |             \
872
0
                              (pake_family) << 16) | (pake_bits)))
873
874
/** The key share being sent to or received from the peer.
875
 *
876
 * The format for both input and output at this step is the same as for public
877
 * keys on the group determined by the primitive (::psa_pake_primitive_t) would
878
 * be.
879
 *
880
 * For more information on the format, consult the documentation of
881
 * psa_export_public_key().
882
 *
883
 * For information regarding how the group is determined, consult the
884
 * documentation #PSA_PAKE_PRIMITIVE.
885
 */
886
0
#define PSA_PAKE_STEP_KEY_SHARE                 ((psa_pake_step_t) 0x01)
887
888
/** A Schnorr NIZKP public key.
889
 *
890
 * This is the ephemeral public key in the Schnorr Non-Interactive
891
 * Zero-Knowledge Proof (the value denoted by the letter 'V' in RFC 8235).
892
 *
893
 * The format for both input and output at this step is the same as for public
894
 * keys on the group determined by the primitive (::psa_pake_primitive_t) would
895
 * be.
896
 *
897
 * For more information on the format, consult the documentation of
898
 * psa_export_public_key().
899
 *
900
 * For information regarding how the group is determined, consult the
901
 * documentation #PSA_PAKE_PRIMITIVE.
902
 */
903
0
#define PSA_PAKE_STEP_ZK_PUBLIC                 ((psa_pake_step_t) 0x02)
904
905
/** A Schnorr NIZKP proof.
906
 *
907
 * This is the proof in the Schnorr Non-Interactive Zero-Knowledge Proof (the
908
 * value denoted by the letter 'r' in RFC 8235).
909
 *
910
 * Both for input and output, the value at this step is an integer less than
911
 * the order of the group selected in the cipher suite. The format depends on
912
 * the group as well:
913
 *
914
 * - For Montgomery curves, the encoding is little endian.
915
 * - For everything else the encoding is big endian (see Section 2.3.8 of
916
 *   _SEC 1: Elliptic Curve Cryptography_ at https://www.secg.org/sec1-v2.pdf).
917
 *
918
 * In both cases leading zeroes are allowed as long as the length in bytes does
919
 * not exceed the byte length of the group order.
920
 *
921
 * For information regarding how the group is determined, consult the
922
 * documentation #PSA_PAKE_PRIMITIVE.
923
 */
924
0
#define PSA_PAKE_STEP_ZK_PROOF                  ((psa_pake_step_t) 0x03)
925
926
/** The type of the data structure for PAKE cipher suites.
927
 *
928
 * This is an implementation-defined \c struct. Applications should not
929
 * make any assumptions about the content of this structure.
930
 * Implementation details can change in future versions without notice.
931
 */
932
typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t;
933
934
/** Return an initial value for a PAKE cipher suite object.
935
 */
936
static psa_pake_cipher_suite_t psa_pake_cipher_suite_init(void);
937
938
/** Retrieve the PAKE algorithm from a PAKE cipher suite.
939
 *
940
 * \param[in] cipher_suite     The cipher suite structure to query.
941
 *
942
 * \return The PAKE algorithm stored in the cipher suite structure.
943
 */
944
static psa_algorithm_t psa_pake_cs_get_algorithm(
945
    const psa_pake_cipher_suite_t *cipher_suite);
946
947
/** Declare the PAKE algorithm for the cipher suite.
948
 *
949
 * This function overwrites any PAKE algorithm
950
 * previously set in \p cipher_suite.
951
 *
952
 * \param[out] cipher_suite    The cipher suite structure to write to.
953
 * \param algorithm            The PAKE algorithm to write.
954
 *                             (`PSA_ALG_XXX` values of type ::psa_algorithm_t
955
 *                             such that #PSA_ALG_IS_PAKE(\c alg) is true.)
956
 *                             If this is 0, the PAKE algorithm in
957
 *                             \p cipher_suite becomes unspecified.
958
 */
959
static void psa_pake_cs_set_algorithm(psa_pake_cipher_suite_t *cipher_suite,
960
                                      psa_algorithm_t algorithm);
961
962
/** Retrieve the primitive from a PAKE cipher suite.
963
 *
964
 * \param[in] cipher_suite     The cipher suite structure to query.
965
 *
966
 * \return The primitive stored in the cipher suite structure.
967
 */
968
static psa_pake_primitive_t psa_pake_cs_get_primitive(
969
    const psa_pake_cipher_suite_t *cipher_suite);
970
971
/** Declare the primitive for a PAKE cipher suite.
972
 *
973
 * This function overwrites any primitive previously set in \p cipher_suite.
974
 *
975
 * \param[out] cipher_suite    The cipher suite structure to write to.
976
 * \param primitive            The primitive to write. If this is 0, the
977
 *                             primitive type in \p cipher_suite becomes
978
 *                             unspecified.
979
 */
980
static void psa_pake_cs_set_primitive(psa_pake_cipher_suite_t *cipher_suite,
981
                                      psa_pake_primitive_t primitive);
982
983
/** Retrieve the PAKE family from a PAKE cipher suite.
984
 *
985
 * \param[in] cipher_suite     The cipher suite structure to query.
986
 *
987
 * \return The PAKE family stored in the cipher suite structure.
988
 */
989
static psa_pake_family_t psa_pake_cs_get_family(
990
    const psa_pake_cipher_suite_t *cipher_suite);
991
992
/** Retrieve the PAKE primitive bit-size from a PAKE cipher suite.
993
 *
994
 * \param[in] cipher_suite     The cipher suite structure to query.
995
 *
996
 * \return The PAKE primitive bit-size stored in the cipher suite structure.
997
 */
998
static uint16_t psa_pake_cs_get_bits(
999
    const psa_pake_cipher_suite_t *cipher_suite);
1000
1001
/** Retrieve the hash algorithm from a PAKE cipher suite.
1002
 *
1003
 * \param[in] cipher_suite      The cipher suite structure to query.
1004
 *
1005
 * \return The hash algorithm stored in the cipher suite structure. The return
1006
 *         value is 0 if the PAKE is not parametrised by a hash algorithm or if
1007
 *         the hash algorithm is not set.
1008
 */
1009
static psa_algorithm_t psa_pake_cs_get_hash(
1010
    const psa_pake_cipher_suite_t *cipher_suite);
1011
1012
/** Declare the hash algorithm for a PAKE cipher suite.
1013
 *
1014
 * This function overwrites any hash algorithm
1015
 * previously set in \p cipher_suite.
1016
 *
1017
 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
1018
 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
1019
 * for more information.
1020
 *
1021
 * \param[out] cipher_suite     The cipher suite structure to write to.
1022
 * \param hash                  The hash involved in the cipher suite.
1023
 *                              (`PSA_ALG_XXX` values of type ::psa_algorithm_t
1024
 *                              such that #PSA_ALG_IS_HASH(\c alg) is true.)
1025
 *                              If this is 0, the hash algorithm in
1026
 *                              \p cipher_suite becomes unspecified.
1027
 */
1028
static void psa_pake_cs_set_hash(psa_pake_cipher_suite_t *cipher_suite,
1029
                                 psa_algorithm_t hash);
1030
1031
/** The type of the state data structure for PAKE operations.
1032
 *
1033
 * Before calling any function on a PAKE operation object, the application
1034
 * must initialize it by any of the following means:
1035
 * - Set the structure to all-bits-zero, for example:
1036
 *   \code
1037
 *   psa_pake_operation_t operation;
1038
 *   memset(&operation, 0, sizeof(operation));
1039
 *   \endcode
1040
 * - Initialize the structure to logical zero values, for example:
1041
 *   \code
1042
 *   psa_pake_operation_t operation = {0};
1043
 *   \endcode
1044
 * - Initialize the structure to the initializer #PSA_PAKE_OPERATION_INIT,
1045
 *   for example:
1046
 *   \code
1047
 *   psa_pake_operation_t operation = PSA_PAKE_OPERATION_INIT;
1048
 *   \endcode
1049
 * - Assign the result of the function psa_pake_operation_init()
1050
 *   to the structure, for example:
1051
 *   \code
1052
 *   psa_pake_operation_t operation;
1053
 *   operation = psa_pake_operation_init();
1054
 *   \endcode
1055
 *
1056
 * This is an implementation-defined \c struct. Applications should not
1057
 * make any assumptions about the content of this structure.
1058
 * Implementation details can change in future versions without notice. */
1059
typedef struct psa_pake_operation_s psa_pake_operation_t;
1060
1061
/** The type of input values for PAKE operations. */
1062
typedef struct psa_crypto_driver_pake_inputs_s psa_crypto_driver_pake_inputs_t;
1063
1064
/** The type of computation stage for J-PAKE operations. */
1065
typedef struct psa_jpake_computation_stage_s psa_jpake_computation_stage_t;
1066
1067
/** Return an initial value for a PAKE operation object.
1068
 */
1069
static psa_pake_operation_t psa_pake_operation_init(void);
1070
1071
/** Get the length of the password in bytes from given inputs.
1072
 *
1073
 * \param[in]  inputs           Operation inputs.
1074
 * \param[out] password_len     Password length.
1075
 *
1076
 * \retval #PSA_SUCCESS
1077
 *         Success.
1078
 * \retval #PSA_ERROR_BAD_STATE
1079
 *         Password hasn't been set yet.
1080
 */
1081
psa_status_t psa_crypto_driver_pake_get_password_len(
1082
    const psa_crypto_driver_pake_inputs_t *inputs,
1083
    size_t *password_len);
1084
1085
/** Get the password from given inputs.
1086
 *
1087
 * \param[in]  inputs           Operation inputs.
1088
 * \param[out] buffer           Return buffer for password.
1089
 * \param      buffer_size      Size of the return buffer in bytes.
1090
 * \param[out] buffer_length    Actual size of the password in bytes.
1091
 *
1092
 * \retval #PSA_SUCCESS
1093
 *         Success.
1094
 * \retval #PSA_ERROR_BAD_STATE
1095
 *         Password hasn't been set yet.
1096
 */
1097
psa_status_t psa_crypto_driver_pake_get_password(
1098
    const psa_crypto_driver_pake_inputs_t *inputs,
1099
    uint8_t *buffer, size_t buffer_size, size_t *buffer_length);
1100
1101
/** Get the length of the user id in bytes from given inputs.
1102
 *
1103
 * \param[in]  inputs           Operation inputs.
1104
 * \param[out] user_len         User id length.
1105
 *
1106
 * \retval #PSA_SUCCESS
1107
 *         Success.
1108
 * \retval #PSA_ERROR_BAD_STATE
1109
 *         User id hasn't been set yet.
1110
 */
1111
psa_status_t psa_crypto_driver_pake_get_user_len(
1112
    const psa_crypto_driver_pake_inputs_t *inputs,
1113
    size_t *user_len);
1114
1115
/** Get the length of the peer id in bytes from given inputs.
1116
 *
1117
 * \param[in]  inputs           Operation inputs.
1118
 * \param[out] peer_len         Peer id length.
1119
 *
1120
 * \retval #PSA_SUCCESS
1121
 *         Success.
1122
 * \retval #PSA_ERROR_BAD_STATE
1123
 *         Peer id hasn't been set yet.
1124
 */
1125
psa_status_t psa_crypto_driver_pake_get_peer_len(
1126
    const psa_crypto_driver_pake_inputs_t *inputs,
1127
    size_t *peer_len);
1128
1129
/** Get the user id from given inputs.
1130
 *
1131
 * \param[in]  inputs           Operation inputs.
1132
 * \param[out] user_id          User id.
1133
 * \param      user_id_size     Size of \p user_id in bytes.
1134
 * \param[out] user_id_len      Size of the user id in bytes.
1135
 *
1136
 * \retval #PSA_SUCCESS
1137
 *         Success.
1138
 * \retval #PSA_ERROR_BAD_STATE
1139
 *         User id hasn't been set yet.
1140
 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1141
 *         The size of the \p user_id is too small.
1142
 */
1143
psa_status_t psa_crypto_driver_pake_get_user(
1144
    const psa_crypto_driver_pake_inputs_t *inputs,
1145
    uint8_t *user_id, size_t user_id_size, size_t *user_id_len);
1146
1147
/** Get the peer id from given inputs.
1148
 *
1149
 * \param[in]  inputs           Operation inputs.
1150
 * \param[out] peer_id          Peer id.
1151
 * \param      peer_id_size     Size of \p peer_id in bytes.
1152
 * \param[out] peer_id_length   Size of the peer id in bytes.
1153
 *
1154
 * \retval #PSA_SUCCESS
1155
 *         Success.
1156
 * \retval #PSA_ERROR_BAD_STATE
1157
 *         Peer id hasn't been set yet.
1158
 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1159
 *         The size of the \p peer_id is too small.
1160
 */
1161
psa_status_t psa_crypto_driver_pake_get_peer(
1162
    const psa_crypto_driver_pake_inputs_t *inputs,
1163
    uint8_t *peer_id, size_t peer_id_size, size_t *peer_id_length);
1164
1165
/** Get the cipher suite from given inputs.
1166
 *
1167
 * \param[in]  inputs           Operation inputs.
1168
 * \param[out] cipher_suite     Return buffer for role.
1169
 *
1170
 * \retval #PSA_SUCCESS
1171
 *         Success.
1172
 * \retval #PSA_ERROR_BAD_STATE
1173
 *         Cipher_suite hasn't been set yet.
1174
 */
1175
psa_status_t psa_crypto_driver_pake_get_cipher_suite(
1176
    const psa_crypto_driver_pake_inputs_t *inputs,
1177
    psa_pake_cipher_suite_t *cipher_suite);
1178
1179
/** Set the session information for a password-authenticated key exchange.
1180
 *
1181
 * The sequence of operations to set up a password-authenticated key exchange
1182
 * is as follows:
1183
 * -# Allocate an operation object which will be passed to all the functions
1184
 *    listed here.
1185
 * -# Initialize the operation object with one of the methods described in the
1186
 *    documentation for #psa_pake_operation_t, e.g.
1187
 *    #PSA_PAKE_OPERATION_INIT.
1188
 * -# Call psa_pake_setup() to specify the cipher suite.
1189
 * -# Call \c psa_pake_set_xxx() functions on the operation to complete the
1190
 *    setup. The exact sequence of \c psa_pake_set_xxx() functions that needs
1191
 *    to be called depends on the algorithm in use.
1192
 *
1193
 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
1194
 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
1195
 * for more information.
1196
 *
1197
 * A typical sequence of calls to perform a password-authenticated key
1198
 * exchange:
1199
 * -# Call psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to get the
1200
 *    key share that needs to be sent to the peer.
1201
 * -# Call psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to provide
1202
 *    the key share that was received from the peer.
1203
 * -# Depending on the algorithm additional calls to psa_pake_output() and
1204
 *    psa_pake_input() might be necessary.
1205
 * -# Call psa_pake_get_implicit_key() for accessing the shared secret.
1206
 *
1207
 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
1208
 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
1209
 * for more information.
1210
 *
1211
 * If an error occurs at any step after a call to psa_pake_setup(),
1212
 * the operation will need to be reset by a call to psa_pake_abort(). The
1213
 * application may call psa_pake_abort() at any time after the operation
1214
 * has been initialized.
1215
 *
1216
 * After a successful call to psa_pake_setup(), the application must
1217
 * eventually terminate the operation. The following events terminate an
1218
 * operation:
1219
 * - A call to psa_pake_abort().
1220
 * - A successful call to psa_pake_get_implicit_key().
1221
 *
1222
 * \param[in,out] operation     The operation object to set up. It must have
1223
 *                              been initialized but not set up yet.
1224
 * \param[in] cipher_suite      The cipher suite to use. (A cipher suite fully
1225
 *                              characterizes a PAKE algorithm and determines
1226
 *                              the algorithm as well.)
1227
 *
1228
 * \retval #PSA_SUCCESS
1229
 *         Success.
1230
 * \retval #PSA_ERROR_INVALID_ARGUMENT
1231
 *         The algorithm in \p cipher_suite is not a PAKE algorithm, or the
1232
 *         PAKE primitive in \p cipher_suite is not compatible with the
1233
 *         PAKE algorithm, or the hash algorithm in \p cipher_suite is invalid
1234
 *         or not compatible with the PAKE algorithm and primitive.
1235
 * \retval #PSA_ERROR_NOT_SUPPORTED
1236
 *         The algorithm in \p cipher_suite is not a supported PAKE algorithm,
1237
 *         or the PAKE primitive in \p cipher_suite is not supported or not
1238
 *         compatible with the PAKE algorithm, or the hash algorithm in
1239
 *         \p cipher_suite is not supported or not compatible with the PAKE
1240
 *         algorithm and primitive.
1241
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1242
 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1243
 * \retval #PSA_ERROR_BAD_STATE
1244
 *         The operation state is not valid, or
1245
 *         the library has not been previously initialized by psa_crypto_init().
1246
 *         It is implementation-dependent whether a failure to initialize
1247
 *         results in this error code.
1248
 */
1249
psa_status_t psa_pake_setup(psa_pake_operation_t *operation,
1250
                            const psa_pake_cipher_suite_t *cipher_suite);
1251
1252
/** Set the password for a password-authenticated key exchange from key ID.
1253
 *
1254
 * Call this function when the password, or a value derived from the password,
1255
 * is already present in the key store.
1256
 *
1257
 * \param[in,out] operation     The operation object to set the password for. It
1258
 *                              must have been set up by psa_pake_setup() and
1259
 *                              not yet in use (neither psa_pake_output() nor
1260
 *                              psa_pake_input() has been called yet). It must
1261
 *                              be on operation for which the password hasn't
1262
 *                              been set yet (psa_pake_set_password_key()
1263
 *                              hasn't been called yet).
1264
 * \param password              Identifier of the key holding the password or a
1265
 *                              value derived from the password (eg. by a
1266
 *                              memory-hard function).  It must remain valid
1267
 *                              until the operation terminates. It must be of
1268
 *                              type #PSA_KEY_TYPE_PASSWORD or
1269
 *                              #PSA_KEY_TYPE_PASSWORD_HASH. It has to allow
1270
 *                              the usage #PSA_KEY_USAGE_DERIVE.
1271
 *
1272
 * \retval #PSA_SUCCESS
1273
 *         Success.
1274
 * \retval #PSA_ERROR_INVALID_HANDLE
1275
 *         \p password is not a valid key identifier.
1276
 * \retval #PSA_ERROR_NOT_PERMITTED
1277
 *         The key does not have the #PSA_KEY_USAGE_DERIVE flag, or it does not
1278
 *         permit the \p operation's algorithm.
1279
 * \retval #PSA_ERROR_INVALID_ARGUMENT
1280
 *         The key type for \p password is not #PSA_KEY_TYPE_PASSWORD or
1281
 *         #PSA_KEY_TYPE_PASSWORD_HASH, or \p password is not compatible with
1282
 *         the \p operation's cipher suite.
1283
 * \retval #PSA_ERROR_NOT_SUPPORTED
1284
 *         The key type or key size of \p password is not supported with the
1285
 *         \p operation's cipher suite.
1286
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1287
 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1288
 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
1289
 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
1290
 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
1291
 * \retval #PSA_ERROR_BAD_STATE
1292
 *         The operation state is not valid (it must have been set up.), or
1293
 *         the library has not been previously initialized by psa_crypto_init().
1294
 *         It is implementation-dependent whether a failure to initialize
1295
 *         results in this error code.
1296
 */
1297
psa_status_t psa_pake_set_password_key(psa_pake_operation_t *operation,
1298
                                       mbedtls_svc_key_id_t password);
1299
1300
/** Set the user ID for a password-authenticated key exchange.
1301
 *
1302
 * Call this function to set the user ID. For PAKE algorithms that associate a
1303
 * user identifier with each side of the session you need to call
1304
 * psa_pake_set_peer() as well. For PAKE algorithms that associate a single
1305
 * user identifier with the session, call psa_pake_set_user() only.
1306
 *
1307
 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
1308
 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
1309
 * for more information.
1310
 *
1311
 * \param[in,out] operation     The operation object to set the user ID for. It
1312
 *                              must have been set up by psa_pake_setup() and
1313
 *                              not yet in use (neither psa_pake_output() nor
1314
 *                              psa_pake_input() has been called yet). It must
1315
 *                              be on operation for which the user ID hasn't
1316
 *                              been set (psa_pake_set_user() hasn't been
1317
 *                              called yet).
1318
 * \param[in] user_id           The user ID to authenticate with.
1319
 * \param user_id_len           Size of the \p user_id buffer in bytes.
1320
 *
1321
 * \retval #PSA_SUCCESS
1322
 *         Success.
1323
 * \retval #PSA_ERROR_INVALID_ARGUMENT
1324
 *         \p user_id is not valid for the \p operation's algorithm and cipher
1325
 *         suite.
1326
 * \retval #PSA_ERROR_NOT_SUPPORTED
1327
 *         The value of \p user_id is not supported by the implementation.
1328
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
1329
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1330
 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1331
 * \retval #PSA_ERROR_BAD_STATE
1332
 *         The operation state is not valid, or
1333
 *         the library has not been previously initialized by psa_crypto_init().
1334
 *         It is implementation-dependent whether a failure to initialize
1335
 *         results in this error code.
1336
 */
1337
psa_status_t psa_pake_set_user(psa_pake_operation_t *operation,
1338
                               const uint8_t *user_id,
1339
                               size_t user_id_len);
1340
1341
/** Set the peer ID for a password-authenticated key exchange.
1342
 *
1343
 * Call this function in addition to psa_pake_set_user() for PAKE algorithms
1344
 * that associate a user identifier with each side of the session. For PAKE
1345
 * algorithms that associate a single user identifier with the session, call
1346
 * psa_pake_set_user() only.
1347
 *
1348
 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
1349
 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
1350
 * for more information.
1351
 *
1352
 * \param[in,out] operation     The operation object to set the peer ID for. It
1353
 *                              must have been set up by psa_pake_setup() and
1354
 *                              not yet in use (neither psa_pake_output() nor
1355
 *                              psa_pake_input() has been called yet). It must
1356
 *                              be on operation for which the peer ID hasn't
1357
 *                              been set (psa_pake_set_peer() hasn't been
1358
 *                              called yet).
1359
 * \param[in] peer_id           The peer's ID to authenticate.
1360
 * \param peer_id_len           Size of the \p peer_id buffer in bytes.
1361
 *
1362
 * \retval #PSA_SUCCESS
1363
 *         Success.
1364
 * \retval #PSA_ERROR_INVALID_ARGUMENT
1365
 *         \p peer_id is not valid for the \p operation's algorithm and cipher
1366
 *         suite.
1367
 * \retval #PSA_ERROR_NOT_SUPPORTED
1368
 *         The algorithm doesn't associate a second identity with the session.
1369
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
1370
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1371
 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1372
 * \retval #PSA_ERROR_BAD_STATE
1373
 *         Calling psa_pake_set_peer() is invalid with the \p operation's
1374
 *         algorithm, the operation state is not valid, or the library has not
1375
 *         been previously initialized by psa_crypto_init().
1376
 *         It is implementation-dependent whether a failure to initialize
1377
 *         results in this error code.
1378
 */
1379
psa_status_t psa_pake_set_peer(psa_pake_operation_t *operation,
1380
                               const uint8_t *peer_id,
1381
                               size_t peer_id_len);
1382
1383
/** Set the application role for a password-authenticated key exchange.
1384
 *
1385
 * Not all PAKE algorithms need to differentiate the communicating entities.
1386
 * It is optional to call this function for PAKEs that don't require a role
1387
 * to be specified. For such PAKEs the application role parameter is ignored,
1388
 * or #PSA_PAKE_ROLE_NONE can be passed as \c role.
1389
 *
1390
 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
1391
 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
1392
 * for more information.
1393
 *
1394
 * \param[in,out] operation     The operation object to specify the
1395
 *                              application's role for. It must have been set up
1396
 *                              by psa_pake_setup() and not yet in use (neither
1397
 *                              psa_pake_output() nor psa_pake_input() has been
1398
 *                              called yet). It must be on operation for which
1399
 *                              the application's role hasn't been specified
1400
 *                              (psa_pake_set_role() hasn't been called yet).
1401
 * \param role                  A value of type ::psa_pake_role_t indicating the
1402
 *                              application's role in the PAKE the algorithm
1403
 *                              that is being set up. For more information see
1404
 *                              the documentation of \c PSA_PAKE_ROLE_XXX
1405
 *                              constants.
1406
 *
1407
 * \retval #PSA_SUCCESS
1408
 *         Success.
1409
 * \retval #PSA_ERROR_INVALID_ARGUMENT
1410
 *         The \p role is not a valid PAKE role in the \p operation’s algorithm.
1411
 * \retval #PSA_ERROR_NOT_SUPPORTED
1412
 *         The \p role for this algorithm is not supported or is not valid.
1413
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1414
 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1415
 * \retval #PSA_ERROR_BAD_STATE
1416
 *         The operation state is not valid, or
1417
 *         the library has not been previously initialized by psa_crypto_init().
1418
 *         It is implementation-dependent whether a failure to initialize
1419
 *         results in this error code.
1420
 */
1421
psa_status_t psa_pake_set_role(psa_pake_operation_t *operation,
1422
                               psa_pake_role_t role);
1423
1424
/** Get output for a step of a password-authenticated key exchange.
1425
 *
1426
 * Depending on the algorithm being executed, you might need to call this
1427
 * function several times or you might not need to call this at all.
1428
 *
1429
 * The exact sequence of calls to perform a password-authenticated key
1430
 * exchange depends on the algorithm in use.  Refer to the documentation of
1431
 * individual PAKE algorithm types (`PSA_ALG_XXX` values of type
1432
 * ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
1433
 * information.
1434
 *
1435
 * If this function returns an error status, the operation enters an error
1436
 * state and must be aborted by calling psa_pake_abort().
1437
 *
1438
 * \param[in,out] operation    Active PAKE operation.
1439
 * \param step                 The step of the algorithm for which the output is
1440
 *                             requested.
1441
 * \param[out] output          Buffer where the output is to be written in the
1442
 *                             format appropriate for this \p step. Refer to
1443
 *                             the documentation of the individual
1444
 *                             \c PSA_PAKE_STEP_XXX constants for more
1445
 *                             information.
1446
 * \param output_size          Size of the \p output buffer in bytes. This must
1447
 *                             be at least #PSA_PAKE_OUTPUT_SIZE(\c alg, \c
1448
 *                             primitive, \p output_step) where \c alg and
1449
 *                             \p primitive are the PAKE algorithm and primitive
1450
 *                             in the operation's cipher suite, and \p step is
1451
 *                             the output step.
1452
 *
1453
 * \param[out] output_length   On success, the number of bytes of the returned
1454
 *                             output.
1455
 *
1456
 * \retval #PSA_SUCCESS
1457
 *         Success.
1458
 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1459
 *         The size of the \p output buffer is too small.
1460
 * \retval #PSA_ERROR_INVALID_ARGUMENT
1461
 *         \p step is not compatible with the operation's algorithm.
1462
 * \retval #PSA_ERROR_NOT_SUPPORTED
1463
 *         \p step is not supported with the operation's algorithm.
1464
 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription
1465
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
1466
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1467
 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1468
 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
1469
 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
1470
 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
1471
 * \retval #PSA_ERROR_BAD_STATE
1472
 *         The operation state is not valid (it must be active, and fully set
1473
 *         up, and this call must conform to the algorithm's requirements
1474
 *         for ordering of input and output steps), or
1475
 *         the library has not been previously initialized by psa_crypto_init().
1476
 *         It is implementation-dependent whether a failure to initialize
1477
 *         results in this error code.
1478
 */
1479
psa_status_t psa_pake_output(psa_pake_operation_t *operation,
1480
                             psa_pake_step_t step,
1481
                             uint8_t *output,
1482
                             size_t output_size,
1483
                             size_t *output_length);
1484
1485
/** Provide input for a step of a password-authenticated key exchange.
1486
 *
1487
 * Depending on the algorithm being executed, you might need to call this
1488
 * function several times or you might not need to call this at all.
1489
 *
1490
 * The exact sequence of calls to perform a password-authenticated key
1491
 * exchange depends on the algorithm in use.  Refer to the documentation of
1492
 * individual PAKE algorithm types (`PSA_ALG_XXX` values of type
1493
 * ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
1494
 * information.
1495
 *
1496
 * If this function returns an error status, the operation enters an error
1497
 * state and must be aborted by calling psa_pake_abort().
1498
 *
1499
 * \param[in,out] operation    Active PAKE operation.
1500
 * \param step                 The step for which the input is provided.
1501
 * \param[in] input            Buffer containing the input in the format
1502
 *                             appropriate for this \p step. Refer to the
1503
 *                             documentation of the individual
1504
 *                             \c PSA_PAKE_STEP_XXX constants for more
1505
 *                             information.
1506
 * \param input_length         Size of the \p input buffer in bytes.
1507
 *
1508
 * \retval #PSA_SUCCESS
1509
 *         Success.
1510
 * \retval #PSA_ERROR_INVALID_SIGNATURE
1511
 *         The verification fails for a #PSA_PAKE_STEP_ZK_PROOF input step.
1512
 * \retval #PSA_ERROR_INVALID_ARGUMENT
1513
 *         \p input_length is not compatible with the \p operation’s algorithm,
1514
 *         or the \p input is not valid for the \p operation's algorithm,
1515
 *         cipher suite or \p step.
1516
 * \retval #PSA_ERROR_NOT_SUPPORTED
1517
 *         \p step p is not supported with the \p operation's algorithm, or the
1518
 *         \p input is not supported for the \p operation's algorithm, cipher
1519
 *         suite or \p step.
1520
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
1521
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1522
 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1523
 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
1524
 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
1525
 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
1526
 * \retval #PSA_ERROR_BAD_STATE
1527
 *         The operation state is not valid (it must be active, and fully set
1528
 *         up, and this call must conform to the algorithm's requirements
1529
 *         for ordering of input and output steps), or
1530
 *         the library has not been previously initialized by psa_crypto_init().
1531
 *         It is implementation-dependent whether a failure to initialize
1532
 *         results in this error code.
1533
 */
1534
psa_status_t psa_pake_input(psa_pake_operation_t *operation,
1535
                            psa_pake_step_t step,
1536
                            const uint8_t *input,
1537
                            size_t input_length);
1538
1539
/** Get implicitly confirmed shared secret from a PAKE.
1540
 *
1541
 * At this point there is a cryptographic guarantee that only the authenticated
1542
 * party who used the same password is able to compute the key. But there is no
1543
 * guarantee that the peer is the party it claims to be and was able to do so.
1544
 *
1545
 * That is, the authentication is only implicit. Since the peer is not
1546
 * authenticated yet, no action should be taken yet that assumes that the peer
1547
 * is who it claims to be. For example, do not access restricted files on the
1548
 * peer's behalf until an explicit authentication has succeeded.
1549
 *
1550
 * This function can be called after the key exchange phase of the operation
1551
 * has completed. It imports the shared secret output of the PAKE into the
1552
 * provided derivation operation. The input step
1553
 * #PSA_KEY_DERIVATION_INPUT_SECRET is used when placing the shared key
1554
 * material in the key derivation operation.
1555
 *
1556
 * The exact sequence of calls to perform a password-authenticated key
1557
 * exchange depends on the algorithm in use.  Refer to the documentation of
1558
 * individual PAKE algorithm types (`PSA_ALG_XXX` values of type
1559
 * ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
1560
 * information.
1561
 *
1562
 * When this function returns successfully, \p operation becomes inactive.
1563
 * If this function returns an error status, both \p operation
1564
 * and \c key_derivation operations enter an error state and must be aborted by
1565
 * calling psa_pake_abort() and psa_key_derivation_abort() respectively.
1566
 *
1567
 * \param[in,out] operation    Active PAKE operation.
1568
 * \param[out] output          A key derivation operation that is ready
1569
 *                             for an input step of type
1570
 *                             #PSA_KEY_DERIVATION_INPUT_SECRET.
1571
 *
1572
 * \retval #PSA_SUCCESS
1573
 *         Success.
1574
 * \retval #PSA_ERROR_INVALID_ARGUMENT
1575
 *         #PSA_KEY_DERIVATION_INPUT_SECRET is not compatible with the
1576
 *         algorithm in the \p output key derivation operation.
1577
 * \retval #PSA_ERROR_NOT_SUPPORTED
1578
 *         Input from a PAKE is not supported by the algorithm in the \p output
1579
 *         key derivation operation.
1580
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
1581
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1582
 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1583
 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
1584
 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
1585
 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
1586
 * \retval #PSA_ERROR_BAD_STATE
1587
 *         The PAKE operation state is not valid (it must be active, but beyond
1588
 *         that validity is specific to the algorithm), or
1589
 *         the library has not been previously initialized by psa_crypto_init(),
1590
 *         or the state of \p output is not valid for
1591
 *         the #PSA_KEY_DERIVATION_INPUT_SECRET step. This can happen if the
1592
 *         step is out of order or the application has done this step already
1593
 *         and it may not be repeated.
1594
 *         It is implementation-dependent whether a failure to initialize
1595
 *         results in this error code.
1596
 */
1597
psa_status_t psa_pake_get_implicit_key(psa_pake_operation_t *operation,
1598
                                       psa_key_derivation_operation_t *output);
1599
1600
/** Abort a PAKE operation.
1601
 *
1602
 * Aborting an operation frees all associated resources except for the \c
1603
 * operation structure itself. Once aborted, the operation object can be reused
1604
 * for another operation by calling psa_pake_setup() again.
1605
 *
1606
 * This function may be called at any time after the operation
1607
 * object has been initialized as described in #psa_pake_operation_t.
1608
 *
1609
 * In particular, calling psa_pake_abort() after the operation has been
1610
 * terminated by a call to psa_pake_abort() or psa_pake_get_implicit_key()
1611
 * is safe and has no effect.
1612
 *
1613
 * \param[in,out] operation    The operation to abort.
1614
 *
1615
 * \retval #PSA_SUCCESS
1616
 *         Success.
1617
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
1618
 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
1619
 * \retval #PSA_ERROR_BAD_STATE
1620
 *         The library has not been previously initialized by psa_crypto_init().
1621
 *         It is implementation-dependent whether a failure to initialize
1622
 *         results in this error code.
1623
 */
1624
psa_status_t psa_pake_abort(psa_pake_operation_t *operation);
1625
1626
/**@}*/
1627
1628
/** A sufficient output buffer size for psa_pake_output().
1629
 *
1630
 * If the size of the output buffer is at least this large, it is guaranteed
1631
 * that psa_pake_output() will not fail due to an insufficient output buffer
1632
 * size. The actual size of the output might be smaller in any given call.
1633
 *
1634
 * See also #PSA_PAKE_OUTPUT_MAX_SIZE
1635
 *
1636
 * \param alg           A PAKE algorithm (\c PSA_ALG_XXX value such that
1637
 *                      #PSA_ALG_IS_PAKE(\p alg) is true).
1638
 * \param primitive     A primitive of type ::psa_pake_primitive_t that is
1639
 *                      compatible with algorithm \p alg.
1640
 * \param output_step   A value of type ::psa_pake_step_t that is valid for the
1641
 *                      algorithm \p alg.
1642
 * \return              A sufficient output buffer size for the specified
1643
 *                      PAKE algorithm, primitive, and output step. If the
1644
 *                      PAKE algorithm, primitive, or output step is not
1645
 *                      recognized, or the parameters are incompatible,
1646
 *                      return 0.
1647
 */
1648
#define PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step)               \
1649
    (alg == PSA_ALG_JPAKE &&                                           \
1650
     primitive == PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC,      \
1651
                                     PSA_ECC_FAMILY_SECP_R1, 256) ?    \
1652
     (                                                                 \
1653
         output_step == PSA_PAKE_STEP_KEY_SHARE ? 65 :                   \
1654
         output_step == PSA_PAKE_STEP_ZK_PUBLIC ? 65 :                   \
1655
         32                                                              \
1656
     ) :                                                               \
1657
     0)
1658
1659
/** A sufficient input buffer size for psa_pake_input().
1660
 *
1661
 * The value returned by this macro is guaranteed to be large enough for any
1662
 * valid input to psa_pake_input() in an operation with the specified
1663
 * parameters.
1664
 *
1665
 * See also #PSA_PAKE_INPUT_MAX_SIZE
1666
 *
1667
 * \param alg           A PAKE algorithm (\c PSA_ALG_XXX value such that
1668
 *                      #PSA_ALG_IS_PAKE(\p alg) is true).
1669
 * \param primitive     A primitive of type ::psa_pake_primitive_t that is
1670
 *                      compatible with algorithm \p alg.
1671
 * \param input_step    A value of type ::psa_pake_step_t that is valid for the
1672
 *                      algorithm \p alg.
1673
 * \return              A sufficient input buffer size for the specified
1674
 *                      input, cipher suite and algorithm. If the cipher suite,
1675
 *                      the input type or PAKE algorithm is not recognized, or
1676
 *                      the parameters are incompatible, return 0.
1677
 */
1678
#define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step)                 \
1679
0
    (alg == PSA_ALG_JPAKE &&                                           \
1680
0
     primitive == PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC,      \
1681
0
                                     PSA_ECC_FAMILY_SECP_R1, 256) ?    \
1682
0
     (                                                                 \
1683
0
         input_step == PSA_PAKE_STEP_KEY_SHARE ? 65 :                    \
1684
0
         input_step == PSA_PAKE_STEP_ZK_PUBLIC ? 65 :                    \
1685
0
         32                                                              \
1686
0
     ) :                                                               \
1687
0
     0)
1688
1689
/** Output buffer size for psa_pake_output() for any of the supported PAKE
1690
 * algorithm and primitive suites and output step.
1691
 *
1692
 * This macro must expand to a compile-time constant integer.
1693
 *
1694
 * The value of this macro must be at least as large as the largest value
1695
 * returned by PSA_PAKE_OUTPUT_SIZE()
1696
 *
1697
 * See also #PSA_PAKE_OUTPUT_SIZE(\p alg, \p primitive, \p output_step).
1698
 */
1699
#define PSA_PAKE_OUTPUT_MAX_SIZE 65
1700
1701
/** Input buffer size for psa_pake_input() for any of the supported PAKE
1702
 * algorithm and primitive suites and input step.
1703
 *
1704
 * This macro must expand to a compile-time constant integer.
1705
 *
1706
 * The value of this macro must be at least as large as the largest value
1707
 * returned by PSA_PAKE_INPUT_SIZE()
1708
 *
1709
 * See also #PSA_PAKE_INPUT_SIZE(\p alg, \p primitive, \p output_step).
1710
 */
1711
#define PSA_PAKE_INPUT_MAX_SIZE 65
1712
1713
/** Returns a suitable initializer for a PAKE cipher suite object of type
1714
 * psa_pake_cipher_suite_t.
1715
 */
1716
0
#define PSA_PAKE_CIPHER_SUITE_INIT { PSA_ALG_NONE, 0, 0, 0, PSA_ALG_NONE }
1717
1718
/** Returns a suitable initializer for a PAKE operation object of type
1719
 * psa_pake_operation_t.
1720
 */
1721
#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
1722
#define PSA_PAKE_OPERATION_INIT { 0 }
1723
#else
1724
#define PSA_PAKE_OPERATION_INIT { 0, PSA_ALG_NONE, 0, PSA_PAKE_OPERATION_STAGE_SETUP, \
1725
                                  { 0 }, { { 0 } } }
1726
#endif
1727
1728
struct psa_pake_cipher_suite_s {
1729
    psa_algorithm_t algorithm;
1730
    psa_pake_primitive_type_t type;
1731
    psa_pake_family_t family;
1732
    uint16_t  bits;
1733
    psa_algorithm_t hash;
1734
};
1735
1736
static inline psa_algorithm_t psa_pake_cs_get_algorithm(
1737
    const psa_pake_cipher_suite_t *cipher_suite)
1738
0
{
1739
0
    return cipher_suite->algorithm;
1740
0
}
Unexecuted instantiation: module.cpp:psa_pake_cs_get_algorithm(psa_pake_cipher_suite_s const*)
Unexecuted instantiation: psa_crypto.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: psa_crypto_aead.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: psa_crypto_cipher.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: psa_crypto_client.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: psa_crypto_ecp.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: psa_crypto_ffdh.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: psa_crypto_hash.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: psa_crypto_mac.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: psa_crypto_pake.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: psa_crypto_rsa.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: psa_crypto_slot_management.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: psa_crypto_storage.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: psa_util.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: rsa.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: md.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: oid.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: pkcs12.c:psa_pake_cs_get_algorithm
Unexecuted instantiation: pkcs5.c:psa_pake_cs_get_algorithm
1741
1742
static inline void psa_pake_cs_set_algorithm(
1743
    psa_pake_cipher_suite_t *cipher_suite,
1744
    psa_algorithm_t algorithm)
1745
0
{
1746
0
    if (!PSA_ALG_IS_PAKE(algorithm)) {
1747
0
        cipher_suite->algorithm = 0;
1748
0
    } else {
1749
0
        cipher_suite->algorithm = algorithm;
1750
0
    }
1751
0
}
Unexecuted instantiation: module.cpp:psa_pake_cs_set_algorithm(psa_pake_cipher_suite_s*, unsigned int)
Unexecuted instantiation: psa_crypto.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: psa_crypto_aead.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: psa_crypto_cipher.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: psa_crypto_client.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: psa_crypto_ecp.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: psa_crypto_ffdh.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: psa_crypto_hash.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: psa_crypto_mac.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: psa_crypto_pake.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: psa_crypto_rsa.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: psa_crypto_slot_management.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: psa_crypto_storage.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: psa_util.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: rsa.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: md.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: oid.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: pkcs12.c:psa_pake_cs_set_algorithm
Unexecuted instantiation: pkcs5.c:psa_pake_cs_set_algorithm
1752
1753
static inline psa_pake_primitive_t psa_pake_cs_get_primitive(
1754
    const psa_pake_cipher_suite_t *cipher_suite)
1755
0
{
1756
0
    return PSA_PAKE_PRIMITIVE(cipher_suite->type, cipher_suite->family,
1757
0
                              cipher_suite->bits);
1758
0
}
Unexecuted instantiation: module.cpp:psa_pake_cs_get_primitive(psa_pake_cipher_suite_s const*)
Unexecuted instantiation: psa_crypto.c:psa_pake_cs_get_primitive
Unexecuted instantiation: psa_crypto_aead.c:psa_pake_cs_get_primitive
Unexecuted instantiation: psa_crypto_cipher.c:psa_pake_cs_get_primitive
Unexecuted instantiation: psa_crypto_client.c:psa_pake_cs_get_primitive
Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_pake_cs_get_primitive
Unexecuted instantiation: psa_crypto_ecp.c:psa_pake_cs_get_primitive
Unexecuted instantiation: psa_crypto_ffdh.c:psa_pake_cs_get_primitive
Unexecuted instantiation: psa_crypto_hash.c:psa_pake_cs_get_primitive
Unexecuted instantiation: psa_crypto_mac.c:psa_pake_cs_get_primitive
Unexecuted instantiation: psa_crypto_pake.c:psa_pake_cs_get_primitive
Unexecuted instantiation: psa_crypto_rsa.c:psa_pake_cs_get_primitive
Unexecuted instantiation: psa_crypto_slot_management.c:psa_pake_cs_get_primitive
Unexecuted instantiation: psa_crypto_storage.c:psa_pake_cs_get_primitive
Unexecuted instantiation: psa_util.c:psa_pake_cs_get_primitive
Unexecuted instantiation: rsa.c:psa_pake_cs_get_primitive
Unexecuted instantiation: md.c:psa_pake_cs_get_primitive
Unexecuted instantiation: oid.c:psa_pake_cs_get_primitive
Unexecuted instantiation: pkcs12.c:psa_pake_cs_get_primitive
Unexecuted instantiation: pkcs5.c:psa_pake_cs_get_primitive
1759
1760
static inline void psa_pake_cs_set_primitive(
1761
    psa_pake_cipher_suite_t *cipher_suite,
1762
    psa_pake_primitive_t primitive)
1763
0
{
1764
0
    cipher_suite->type = (psa_pake_primitive_type_t) (primitive >> 24);
1765
0
    cipher_suite->family = (psa_pake_family_t) (0xFF & (primitive >> 16));
1766
0
    cipher_suite->bits = (uint16_t) (0xFFFF & primitive);
1767
0
}
Unexecuted instantiation: module.cpp:psa_pake_cs_set_primitive(psa_pake_cipher_suite_s*, unsigned int)
Unexecuted instantiation: psa_crypto.c:psa_pake_cs_set_primitive
Unexecuted instantiation: psa_crypto_aead.c:psa_pake_cs_set_primitive
Unexecuted instantiation: psa_crypto_cipher.c:psa_pake_cs_set_primitive
Unexecuted instantiation: psa_crypto_client.c:psa_pake_cs_set_primitive
Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_pake_cs_set_primitive
Unexecuted instantiation: psa_crypto_ecp.c:psa_pake_cs_set_primitive
Unexecuted instantiation: psa_crypto_ffdh.c:psa_pake_cs_set_primitive
Unexecuted instantiation: psa_crypto_hash.c:psa_pake_cs_set_primitive
Unexecuted instantiation: psa_crypto_mac.c:psa_pake_cs_set_primitive
Unexecuted instantiation: psa_crypto_pake.c:psa_pake_cs_set_primitive
Unexecuted instantiation: psa_crypto_rsa.c:psa_pake_cs_set_primitive
Unexecuted instantiation: psa_crypto_slot_management.c:psa_pake_cs_set_primitive
Unexecuted instantiation: psa_crypto_storage.c:psa_pake_cs_set_primitive
Unexecuted instantiation: psa_util.c:psa_pake_cs_set_primitive
Unexecuted instantiation: rsa.c:psa_pake_cs_set_primitive
Unexecuted instantiation: md.c:psa_pake_cs_set_primitive
Unexecuted instantiation: oid.c:psa_pake_cs_set_primitive
Unexecuted instantiation: pkcs12.c:psa_pake_cs_set_primitive
Unexecuted instantiation: pkcs5.c:psa_pake_cs_set_primitive
1768
1769
static inline psa_pake_family_t psa_pake_cs_get_family(
1770
    const psa_pake_cipher_suite_t *cipher_suite)
1771
0
{
1772
0
    return cipher_suite->family;
1773
0
}
Unexecuted instantiation: module.cpp:psa_pake_cs_get_family(psa_pake_cipher_suite_s const*)
Unexecuted instantiation: psa_crypto.c:psa_pake_cs_get_family
Unexecuted instantiation: psa_crypto_aead.c:psa_pake_cs_get_family
Unexecuted instantiation: psa_crypto_cipher.c:psa_pake_cs_get_family
Unexecuted instantiation: psa_crypto_client.c:psa_pake_cs_get_family
Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_pake_cs_get_family
Unexecuted instantiation: psa_crypto_ecp.c:psa_pake_cs_get_family
Unexecuted instantiation: psa_crypto_ffdh.c:psa_pake_cs_get_family
Unexecuted instantiation: psa_crypto_hash.c:psa_pake_cs_get_family
Unexecuted instantiation: psa_crypto_mac.c:psa_pake_cs_get_family
Unexecuted instantiation: psa_crypto_pake.c:psa_pake_cs_get_family
Unexecuted instantiation: psa_crypto_rsa.c:psa_pake_cs_get_family
Unexecuted instantiation: psa_crypto_slot_management.c:psa_pake_cs_get_family
Unexecuted instantiation: psa_crypto_storage.c:psa_pake_cs_get_family
Unexecuted instantiation: psa_util.c:psa_pake_cs_get_family
Unexecuted instantiation: rsa.c:psa_pake_cs_get_family
Unexecuted instantiation: md.c:psa_pake_cs_get_family
Unexecuted instantiation: oid.c:psa_pake_cs_get_family
Unexecuted instantiation: pkcs12.c:psa_pake_cs_get_family
Unexecuted instantiation: pkcs5.c:psa_pake_cs_get_family
1774
1775
static inline uint16_t psa_pake_cs_get_bits(
1776
    const psa_pake_cipher_suite_t *cipher_suite)
1777
0
{
1778
0
    return cipher_suite->bits;
1779
0
}
Unexecuted instantiation: module.cpp:psa_pake_cs_get_bits(psa_pake_cipher_suite_s const*)
Unexecuted instantiation: psa_crypto.c:psa_pake_cs_get_bits
Unexecuted instantiation: psa_crypto_aead.c:psa_pake_cs_get_bits
Unexecuted instantiation: psa_crypto_cipher.c:psa_pake_cs_get_bits
Unexecuted instantiation: psa_crypto_client.c:psa_pake_cs_get_bits
Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_pake_cs_get_bits
Unexecuted instantiation: psa_crypto_ecp.c:psa_pake_cs_get_bits
Unexecuted instantiation: psa_crypto_ffdh.c:psa_pake_cs_get_bits
Unexecuted instantiation: psa_crypto_hash.c:psa_pake_cs_get_bits
Unexecuted instantiation: psa_crypto_mac.c:psa_pake_cs_get_bits
Unexecuted instantiation: psa_crypto_pake.c:psa_pake_cs_get_bits
Unexecuted instantiation: psa_crypto_rsa.c:psa_pake_cs_get_bits
Unexecuted instantiation: psa_crypto_slot_management.c:psa_pake_cs_get_bits
Unexecuted instantiation: psa_crypto_storage.c:psa_pake_cs_get_bits
Unexecuted instantiation: psa_util.c:psa_pake_cs_get_bits
Unexecuted instantiation: rsa.c:psa_pake_cs_get_bits
Unexecuted instantiation: md.c:psa_pake_cs_get_bits
Unexecuted instantiation: oid.c:psa_pake_cs_get_bits
Unexecuted instantiation: pkcs12.c:psa_pake_cs_get_bits
Unexecuted instantiation: pkcs5.c:psa_pake_cs_get_bits
1780
1781
static inline psa_algorithm_t psa_pake_cs_get_hash(
1782
    const psa_pake_cipher_suite_t *cipher_suite)
1783
0
{
1784
0
    return cipher_suite->hash;
1785
0
}
Unexecuted instantiation: module.cpp:psa_pake_cs_get_hash(psa_pake_cipher_suite_s const*)
Unexecuted instantiation: psa_crypto.c:psa_pake_cs_get_hash
Unexecuted instantiation: psa_crypto_aead.c:psa_pake_cs_get_hash
Unexecuted instantiation: psa_crypto_cipher.c:psa_pake_cs_get_hash
Unexecuted instantiation: psa_crypto_client.c:psa_pake_cs_get_hash
Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_pake_cs_get_hash
Unexecuted instantiation: psa_crypto_ecp.c:psa_pake_cs_get_hash
Unexecuted instantiation: psa_crypto_ffdh.c:psa_pake_cs_get_hash
Unexecuted instantiation: psa_crypto_hash.c:psa_pake_cs_get_hash
Unexecuted instantiation: psa_crypto_mac.c:psa_pake_cs_get_hash
Unexecuted instantiation: psa_crypto_pake.c:psa_pake_cs_get_hash
Unexecuted instantiation: psa_crypto_rsa.c:psa_pake_cs_get_hash
Unexecuted instantiation: psa_crypto_slot_management.c:psa_pake_cs_get_hash
Unexecuted instantiation: psa_crypto_storage.c:psa_pake_cs_get_hash
Unexecuted instantiation: psa_util.c:psa_pake_cs_get_hash
Unexecuted instantiation: rsa.c:psa_pake_cs_get_hash
Unexecuted instantiation: md.c:psa_pake_cs_get_hash
Unexecuted instantiation: oid.c:psa_pake_cs_get_hash
Unexecuted instantiation: pkcs12.c:psa_pake_cs_get_hash
Unexecuted instantiation: pkcs5.c:psa_pake_cs_get_hash
1786
1787
static inline void psa_pake_cs_set_hash(psa_pake_cipher_suite_t *cipher_suite,
1788
                                        psa_algorithm_t hash)
1789
0
{
1790
0
    if (!PSA_ALG_IS_HASH(hash)) {
1791
0
        cipher_suite->hash = 0;
1792
0
    } else {
1793
0
        cipher_suite->hash = hash;
1794
0
    }
1795
0
}
Unexecuted instantiation: module.cpp:psa_pake_cs_set_hash(psa_pake_cipher_suite_s*, unsigned int)
Unexecuted instantiation: psa_crypto.c:psa_pake_cs_set_hash
Unexecuted instantiation: psa_crypto_aead.c:psa_pake_cs_set_hash
Unexecuted instantiation: psa_crypto_cipher.c:psa_pake_cs_set_hash
Unexecuted instantiation: psa_crypto_client.c:psa_pake_cs_set_hash
Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_pake_cs_set_hash
Unexecuted instantiation: psa_crypto_ecp.c:psa_pake_cs_set_hash
Unexecuted instantiation: psa_crypto_ffdh.c:psa_pake_cs_set_hash
Unexecuted instantiation: psa_crypto_hash.c:psa_pake_cs_set_hash
Unexecuted instantiation: psa_crypto_mac.c:psa_pake_cs_set_hash
Unexecuted instantiation: psa_crypto_pake.c:psa_pake_cs_set_hash
Unexecuted instantiation: psa_crypto_rsa.c:psa_pake_cs_set_hash
Unexecuted instantiation: psa_crypto_slot_management.c:psa_pake_cs_set_hash
Unexecuted instantiation: psa_crypto_storage.c:psa_pake_cs_set_hash
Unexecuted instantiation: psa_util.c:psa_pake_cs_set_hash
Unexecuted instantiation: rsa.c:psa_pake_cs_set_hash
Unexecuted instantiation: md.c:psa_pake_cs_set_hash
Unexecuted instantiation: oid.c:psa_pake_cs_set_hash
Unexecuted instantiation: pkcs12.c:psa_pake_cs_set_hash
Unexecuted instantiation: pkcs5.c:psa_pake_cs_set_hash
1796
1797
struct psa_crypto_driver_pake_inputs_s {
1798
    uint8_t *MBEDTLS_PRIVATE(password);
1799
    size_t MBEDTLS_PRIVATE(password_len);
1800
    uint8_t *MBEDTLS_PRIVATE(user);
1801
    size_t MBEDTLS_PRIVATE(user_len);
1802
    uint8_t *MBEDTLS_PRIVATE(peer);
1803
    size_t MBEDTLS_PRIVATE(peer_len);
1804
    psa_key_attributes_t MBEDTLS_PRIVATE(attributes);
1805
    psa_pake_cipher_suite_t MBEDTLS_PRIVATE(cipher_suite);
1806
};
1807
1808
typedef enum psa_crypto_driver_pake_step {
1809
    PSA_JPAKE_STEP_INVALID        = 0,  /* Invalid step */
1810
    PSA_JPAKE_X1_STEP_KEY_SHARE   = 1,  /* Round 1: input/output key share (for ephemeral private key X1).*/
1811
    PSA_JPAKE_X1_STEP_ZK_PUBLIC   = 2,  /* Round 1: input/output Schnorr NIZKP public key for the X1 key */
1812
    PSA_JPAKE_X1_STEP_ZK_PROOF    = 3,  /* Round 1: input/output Schnorr NIZKP proof for the X1 key */
1813
    PSA_JPAKE_X2_STEP_KEY_SHARE   = 4,  /* Round 1: input/output key share (for ephemeral private key X2).*/
1814
    PSA_JPAKE_X2_STEP_ZK_PUBLIC   = 5,  /* Round 1: input/output Schnorr NIZKP public key for the X2 key */
1815
    PSA_JPAKE_X2_STEP_ZK_PROOF    = 6,  /* Round 1: input/output Schnorr NIZKP proof for the X2 key */
1816
    PSA_JPAKE_X2S_STEP_KEY_SHARE  = 7,  /* Round 2: output X2S key (our key) */
1817
    PSA_JPAKE_X2S_STEP_ZK_PUBLIC  = 8,  /* Round 2: output Schnorr NIZKP public key for the X2S key (our key) */
1818
    PSA_JPAKE_X2S_STEP_ZK_PROOF   = 9,  /* Round 2: output Schnorr NIZKP proof for the X2S key (our key) */
1819
    PSA_JPAKE_X4S_STEP_KEY_SHARE  = 10, /* Round 2: input X4S key (from peer) */
1820
    PSA_JPAKE_X4S_STEP_ZK_PUBLIC  = 11, /* Round 2: input Schnorr NIZKP public key for the X4S key (from peer) */
1821
    PSA_JPAKE_X4S_STEP_ZK_PROOF   = 12  /* Round 2: input Schnorr NIZKP proof for the X4S key (from peer) */
1822
} psa_crypto_driver_pake_step_t;
1823
1824
typedef enum psa_jpake_round {
1825
    PSA_JPAKE_FIRST = 0,
1826
    PSA_JPAKE_SECOND = 1,
1827
    PSA_JPAKE_FINISHED = 2
1828
} psa_jpake_round_t;
1829
1830
typedef enum psa_jpake_io_mode {
1831
    PSA_JPAKE_INPUT = 0,
1832
    PSA_JPAKE_OUTPUT = 1
1833
} psa_jpake_io_mode_t;
1834
1835
struct psa_jpake_computation_stage_s {
1836
    /* The J-PAKE round we are currently on */
1837
    psa_jpake_round_t MBEDTLS_PRIVATE(round);
1838
    /* The 'mode' we are currently in (inputting or outputting) */
1839
    psa_jpake_io_mode_t MBEDTLS_PRIVATE(io_mode);
1840
    /* The number of completed inputs so far this round */
1841
    uint8_t MBEDTLS_PRIVATE(inputs);
1842
    /* The number of completed outputs so far this round */
1843
    uint8_t MBEDTLS_PRIVATE(outputs);
1844
    /* The next expected step (KEY_SHARE, ZK_PUBLIC or ZK_PROOF) */
1845
    psa_pake_step_t MBEDTLS_PRIVATE(step);
1846
};
1847
1848
0
#define PSA_JPAKE_EXPECTED_INPUTS(round) ((round) == PSA_JPAKE_FINISHED ? 0 : \
1849
0
                                          ((round) == PSA_JPAKE_FIRST ? 2 : 1))
1850
0
#define PSA_JPAKE_EXPECTED_OUTPUTS(round) ((round) == PSA_JPAKE_FINISHED ? 0 : \
1851
0
                                           ((round) == PSA_JPAKE_FIRST ? 2 : 1))
1852
1853
struct psa_pake_operation_s {
1854
#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
1855
    mbedtls_psa_client_handle_t handle;
1856
#else
1857
    /** Unique ID indicating which driver got assigned to do the
1858
     * operation. Since driver contexts are driver-specific, swapping
1859
     * drivers halfway through the operation is not supported.
1860
     * ID values are auto-generated in psa_crypto_driver_wrappers.h
1861
     * ID value zero means the context is not valid or not assigned to
1862
     * any driver (i.e. none of the driver contexts are active). */
1863
    unsigned int MBEDTLS_PRIVATE(id);
1864
    /* Algorithm of the PAKE operation */
1865
    psa_algorithm_t MBEDTLS_PRIVATE(alg);
1866
    /* A primitive of type compatible with algorithm */
1867
    psa_pake_primitive_t MBEDTLS_PRIVATE(primitive);
1868
    /* Stage of the PAKE operation: waiting for the setup, collecting inputs
1869
     * or computing. */
1870
    uint8_t MBEDTLS_PRIVATE(stage);
1871
    /* Holds computation stage of the PAKE algorithms. */
1872
    union {
1873
        uint8_t MBEDTLS_PRIVATE(dummy);
1874
#if defined(PSA_WANT_ALG_JPAKE)
1875
        psa_jpake_computation_stage_t MBEDTLS_PRIVATE(jpake);
1876
#endif
1877
    } MBEDTLS_PRIVATE(computation_stage);
1878
    union {
1879
        psa_driver_pake_context_t MBEDTLS_PRIVATE(ctx);
1880
        psa_crypto_driver_pake_inputs_t MBEDTLS_PRIVATE(inputs);
1881
    } MBEDTLS_PRIVATE(data);
1882
#endif
1883
};
1884
1885
static inline struct psa_pake_cipher_suite_s psa_pake_cipher_suite_init(void)
1886
0
{
1887
0
    const struct psa_pake_cipher_suite_s v = PSA_PAKE_CIPHER_SUITE_INIT;
1888
0
    return v;
1889
0
}
Unexecuted instantiation: module.cpp:psa_pake_cipher_suite_init()
Unexecuted instantiation: psa_crypto.c:psa_pake_cipher_suite_init
Unexecuted instantiation: psa_crypto_aead.c:psa_pake_cipher_suite_init
Unexecuted instantiation: psa_crypto_cipher.c:psa_pake_cipher_suite_init
Unexecuted instantiation: psa_crypto_client.c:psa_pake_cipher_suite_init
Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_pake_cipher_suite_init
Unexecuted instantiation: psa_crypto_ecp.c:psa_pake_cipher_suite_init
Unexecuted instantiation: psa_crypto_ffdh.c:psa_pake_cipher_suite_init
Unexecuted instantiation: psa_crypto_hash.c:psa_pake_cipher_suite_init
Unexecuted instantiation: psa_crypto_mac.c:psa_pake_cipher_suite_init
Unexecuted instantiation: psa_crypto_pake.c:psa_pake_cipher_suite_init
Unexecuted instantiation: psa_crypto_rsa.c:psa_pake_cipher_suite_init
Unexecuted instantiation: psa_crypto_slot_management.c:psa_pake_cipher_suite_init
Unexecuted instantiation: psa_crypto_storage.c:psa_pake_cipher_suite_init
Unexecuted instantiation: psa_util.c:psa_pake_cipher_suite_init
Unexecuted instantiation: rsa.c:psa_pake_cipher_suite_init
Unexecuted instantiation: md.c:psa_pake_cipher_suite_init
Unexecuted instantiation: oid.c:psa_pake_cipher_suite_init
Unexecuted instantiation: pkcs12.c:psa_pake_cipher_suite_init
Unexecuted instantiation: pkcs5.c:psa_pake_cipher_suite_init
1890
1891
static inline struct psa_pake_operation_s psa_pake_operation_init(void)
1892
0
{
1893
0
    const struct psa_pake_operation_s v = PSA_PAKE_OPERATION_INIT;
1894
0
    return v;
1895
0
}
Unexecuted instantiation: module.cpp:psa_pake_operation_init()
Unexecuted instantiation: psa_crypto.c:psa_pake_operation_init
Unexecuted instantiation: psa_crypto_aead.c:psa_pake_operation_init
Unexecuted instantiation: psa_crypto_cipher.c:psa_pake_operation_init
Unexecuted instantiation: psa_crypto_client.c:psa_pake_operation_init
Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:psa_pake_operation_init
Unexecuted instantiation: psa_crypto_ecp.c:psa_pake_operation_init
Unexecuted instantiation: psa_crypto_ffdh.c:psa_pake_operation_init
Unexecuted instantiation: psa_crypto_hash.c:psa_pake_operation_init
Unexecuted instantiation: psa_crypto_mac.c:psa_pake_operation_init
Unexecuted instantiation: psa_crypto_pake.c:psa_pake_operation_init
Unexecuted instantiation: psa_crypto_rsa.c:psa_pake_operation_init
Unexecuted instantiation: psa_crypto_slot_management.c:psa_pake_operation_init
Unexecuted instantiation: psa_crypto_storage.c:psa_pake_operation_init
Unexecuted instantiation: psa_util.c:psa_pake_operation_init
Unexecuted instantiation: rsa.c:psa_pake_operation_init
Unexecuted instantiation: md.c:psa_pake_operation_init
Unexecuted instantiation: oid.c:psa_pake_operation_init
Unexecuted instantiation: pkcs12.c:psa_pake_operation_init
Unexecuted instantiation: pkcs5.c:psa_pake_operation_init
1896
1897
#ifdef __cplusplus
1898
}
1899
#endif
1900
1901
#endif /* PSA_CRYPTO_EXTRA_H */