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
19 #include "mbedtls/platform_util.h"
20
21 #include "crypto_types.h"
22 #include "crypto_compat.h"
23
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27
28 /* UID for secure storage seed */
29 #define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
30
31 /* See config.h for definition */
32 #if !defined(MBEDTLS_PSA_KEY_SLOT_COUNT)
33 #define MBEDTLS_PSA_KEY_SLOT_COUNT 32
34 #endif
35
36 /** \addtogroup attributes
37 * @{
38 */
39
40 /** \brief Declare the enrollment algorithm for a key.
41 *
42 * An operation on a key may indifferently use the algorithm set with
43 * psa_set_key_algorithm() or with this function.
44 *
45 * \param[out] attributes The attribute structure to write to.
46 * \param alg2 A second algorithm that the key may be used
47 * for, in addition to the algorithm set with
48 * psa_set_key_algorithm().
49 *
50 * \warning Setting an enrollment algorithm is not recommended, because
51 * using the same key with different algorithms can allow some
52 * attacks based on arithmetic relations between different
53 * computations made with the same key, or can escalate harmless
54 * side channels into exploitable ones. Use this function only
55 * if it is necessary to support a protocol for which it has been
56 * verified that the usage of the key with multiple algorithms
57 * is safe.
58 */
psa_set_key_enrollment_algorithm(psa_key_attributes_t * attributes,psa_algorithm_t alg2)59 static inline void psa_set_key_enrollment_algorithm(
60 psa_key_attributes_t *attributes,
61 psa_algorithm_t alg2)
62 {
63 attributes->core.policy.alg2 = alg2;
64 }
65
66 /** Retrieve the enrollment algorithm policy from key attributes.
67 *
68 * \param[in] attributes The key attribute structure to query.
69 *
70 * \return The enrollment algorithm stored in the attribute structure.
71 */
psa_get_key_enrollment_algorithm(const psa_key_attributes_t * attributes)72 static inline psa_algorithm_t psa_get_key_enrollment_algorithm(
73 const psa_key_attributes_t *attributes)
74 {
75 return attributes->core.policy.alg2;
76 }
77
78 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
79
80 /** Retrieve the slot number where a key is stored.
81 *
82 * A slot number is only defined for keys that are stored in a secure
83 * element.
84 *
85 * This information is only useful if the secure element is not entirely
86 * managed through the PSA Cryptography API. It is up to the secure
87 * element driver to decide how PSA slot numbers map to any other interface
88 * that the secure element may have.
89 *
90 * \param[in] attributes The key attribute structure to query.
91 * \param[out] slot_number On success, the slot number containing the key.
92 *
93 * \retval #PSA_SUCCESS
94 * The key is located in a secure element, and \p *slot_number
95 * indicates the slot number that contains it.
96 * \retval #PSA_ERROR_NOT_PERMITTED
97 * The caller is not permitted to query the slot number.
98 * Mbed TLS currently does not return this error.
99 * \retval #PSA_ERROR_INVALID_ARGUMENT
100 * The key is not located in a secure element.
101 */
102 psa_status_t psa_get_key_slot_number(
103 const psa_key_attributes_t *attributes,
104 psa_key_slot_number_t *slot_number);
105
106 /** Choose the slot number where a key is stored.
107 *
108 * This function declares a slot number in the specified attribute
109 * structure.
110 *
111 * A slot number is only meaningful for keys that are stored in a secure
112 * element. It is up to the secure element driver to decide how PSA slot
113 * numbers map to any other interface that the secure element may have.
114 *
115 * \note Setting a slot number in key attributes for a key creation can
116 * cause the following errors when creating the key:
117 * - #PSA_ERROR_NOT_SUPPORTED if the selected secure element does
118 * not support choosing a specific slot number.
119 * - #PSA_ERROR_NOT_PERMITTED if the caller is not permitted to
120 * choose slot numbers in general or to choose this specific slot.
121 * - #PSA_ERROR_INVALID_ARGUMENT if the chosen slot number is not
122 * valid in general or not valid for this specific key.
123 * - #PSA_ERROR_ALREADY_EXISTS if there is already a key in the
124 * selected slot.
125 *
126 * \param[out] attributes The attribute structure to write to.
127 * \param slot_number The slot number to set.
128 */
psa_set_key_slot_number(psa_key_attributes_t * attributes,psa_key_slot_number_t slot_number)129 static inline void psa_set_key_slot_number(
130 psa_key_attributes_t *attributes,
131 psa_key_slot_number_t slot_number)
132 {
133 attributes->core.flags |= MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
134 attributes->slot_number = slot_number;
135 }
136
137 /** Remove the slot number attribute from a key attribute structure.
138 *
139 * This function undoes the action of psa_set_key_slot_number().
140 *
141 * \param[out] attributes The attribute structure to write to.
142 */
psa_clear_key_slot_number(psa_key_attributes_t * attributes)143 static inline void psa_clear_key_slot_number(
144 psa_key_attributes_t *attributes)
145 {
146 attributes->core.flags &= ~MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
147 }
148
149 /** Register a key that is already present in a secure element.
150 *
151 * The key must be located in a secure element designated by the
152 * lifetime field in \p attributes, in the slot set with
153 * psa_set_key_slot_number() in the attribute structure.
154 * This function makes the key available through the key identifier
155 * specified in \p attributes.
156 *
157 * \param[in] attributes The attributes of the existing key.
158 *
159 * \retval #PSA_SUCCESS
160 * The key was successfully registered.
161 * Note that depending on the design of the driver, this may or may
162 * not guarantee that a key actually exists in the designated slot
163 * and is compatible with the specified attributes.
164 * \retval #PSA_ERROR_ALREADY_EXISTS
165 * There is already a key with the identifier specified in
166 * \p attributes.
167 * \retval #PSA_ERROR_NOT_SUPPORTED
168 * The secure element driver for the specified lifetime does not
169 * support registering a key.
170 * \retval #PSA_ERROR_INVALID_ARGUMENT
171 * The identifier in \p attributes is invalid, namely the identifier is
172 * not in the user range, or
173 * \p attributes specifies a lifetime which is not located
174 * in a secure element, or no slot number is specified in \p attributes,
175 * or the specified slot number is not valid.
176 * \retval #PSA_ERROR_NOT_PERMITTED
177 * The caller is not authorized to register the specified key slot.
178 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
179 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription
180 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
181 * \retval #PSA_ERROR_DATA_INVALID \emptydescription
182 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
183 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
184 * \retval #PSA_ERROR_BAD_STATE
185 * The library has not been previously initialized by psa_crypto_init().
186 * It is implementation-dependent whether a failure to initialize
187 * results in this error code.
188 */
189 psa_status_t mbedtls_psa_register_se_key(
190 const psa_key_attributes_t *attributes);
191
192 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */
193
194 /**@}*/
195
196 /**
197 * \brief Library deinitialization.
198 *
199 * This function clears all data associated with the PSA layer,
200 * including the whole key store.
201 *
202 * This is an Mbed TLS extension.
203 */
204 void mbedtls_psa_crypto_free(void);
205
206 /** \brief Statistics about
207 * resource consumption related to the PSA keystore.
208 *
209 * \note The content of this structure is not part of the stable API and ABI
210 * of Mbed TLS and may change arbitrarily from version to version.
211 */
212 typedef struct mbedtls_psa_stats_s {
213 /** Number of slots containing key material for a volatile key. */
214 size_t volatile_slots;
215 /** Number of slots containing key material for a key which is in
216 * internal persistent storage. */
217 size_t persistent_slots;
218 /** Number of slots containing a reference to a key in a
219 * secure element. */
220 size_t external_slots;
221 /** Number of slots which are occupied, but do not contain
222 * key material yet. */
223 size_t half_filled_slots;
224 /** Number of slots that contain cache data. */
225 size_t cache_slots;
226 /** Number of slots that are not used for anything. */
227 size_t empty_slots;
228 /** Number of slots that are locked. */
229 size_t locked_slots;
230 /** Largest key id value among open keys in internal persistent storage. */
231 psa_key_id_t max_open_internal_key_id;
232 /** Largest key id value among open keys in secure elements. */
233 psa_key_id_t max_open_external_key_id;
234 } mbedtls_psa_stats_t;
235
236 /** \brief Get statistics about
237 * resource consumption related to the PSA keystore.
238 *
239 * \note When Mbed TLS is built as part of a service, with isolation
240 * between the application and the keystore, the service may or
241 * may not expose this function.
242 */
243 void mbedtls_psa_get_stats(mbedtls_psa_stats_t *stats);
244
245 /**
246 * \brief Inject an initial entropy seed for the random generator into
247 * secure storage.
248 *
249 * This function injects data to be used as a seed for the random generator
250 * used by the PSA Crypto implementation. On devices that lack a trusted
251 * entropy source (preferably a hardware random number generator),
252 * the Mbed PSA Crypto implementation uses this value to seed its
253 * random generator.
254 *
255 * On devices without a trusted entropy source, this function must be
256 * called exactly once in the lifetime of the device. On devices with
257 * a trusted entropy source, calling this function is optional.
258 * In all cases, this function may only be called before calling any
259 * other function in the PSA Crypto API, including psa_crypto_init().
260 *
261 * When this function returns successfully, it populates a file in
262 * persistent storage. Once the file has been created, this function
263 * can no longer succeed.
264 *
265 * If any error occurs, this function does not change the system state.
266 * You can call this function again after correcting the reason for the
267 * error if possible.
268 *
269 * \warning This function **can** fail! Callers MUST check the return status.
270 *
271 * \warning If you use this function, you should use it as part of a
272 * factory provisioning process. The value of the injected seed
273 * is critical to the security of the device. It must be
274 * *secret*, *unpredictable* and (statistically) *unique per device*.
275 * You should be generate it randomly using a cryptographically
276 * secure random generator seeded from trusted entropy sources.
277 * You should transmit it securely to the device and ensure
278 * that its value is not leaked or stored anywhere beyond the
279 * needs of transmitting it from the point of generation to
280 * the call of this function, and erase all copies of the value
281 * once this function returns.
282 *
283 * This is an Mbed TLS extension.
284 *
285 * \note This function is only available on the following platforms:
286 * * If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled.
287 * Note that you must provide compatible implementations of
288 * mbedtls_nv_seed_read and mbedtls_nv_seed_write.
289 * * In a client-server integration of PSA Cryptography, on the client side,
290 * if the server supports this feature.
291 * \param[in] seed Buffer containing the seed value to inject.
292 * \param[in] seed_size Size of the \p seed buffer.
293 * The size of the seed in bytes must be greater
294 * or equal to both #MBEDTLS_ENTROPY_MIN_PLATFORM
295 * and #MBEDTLS_ENTROPY_BLOCK_SIZE.
296 * It must be less or equal to
297 * #MBEDTLS_ENTROPY_MAX_SEED_SIZE.
298 *
299 * \retval #PSA_SUCCESS
300 * The seed value was injected successfully. The random generator
301 * of the PSA Crypto implementation is now ready for use.
302 * You may now call psa_crypto_init() and use the PSA Crypto
303 * implementation.
304 * \retval #PSA_ERROR_INVALID_ARGUMENT
305 * \p seed_size is out of range.
306 * \retval #PSA_ERROR_STORAGE_FAILURE
307 * There was a failure reading or writing from storage.
308 * \retval #PSA_ERROR_NOT_PERMITTED
309 * The library has already been initialized. It is no longer
310 * possible to call this function.
311 */
312 psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed,
313 size_t seed_size);
314
315 /** \addtogroup crypto_types
316 * @{
317 */
318
319 /** DSA public key.
320 *
321 * The import and export format is the
322 * representation of the public key `y = g^x mod p` as a big-endian byte
323 * string. The length of the byte string is the length of the base prime `p`
324 * in bytes.
325 */
326 #define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t) 0x4002)
327
328 /** DSA key pair (private and public key).
329 *
330 * The import and export format is the
331 * representation of the private key `x` as a big-endian byte string. The
332 * length of the byte string is the private key size in bytes (leading zeroes
333 * are not stripped).
334 *
335 * Deterministic DSA key derivation with psa_generate_derived_key follows
336 * FIPS 186-4 §B.1.2: interpret the byte string as integer
337 * in big-endian order. Discard it if it is not in the range
338 * [0, *N* - 2] where *N* is the boundary of the private key domain
339 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
340 * or the order of the curve's base point for ECC).
341 * Add 1 to the resulting integer and use this as the private key *x*.
342 *
343 */
344 #define PSA_KEY_TYPE_DSA_KEY_PAIR ((psa_key_type_t) 0x7002)
345
346 /** Whether a key type is a DSA key (pair or public-only). */
347 #define PSA_KEY_TYPE_IS_DSA(type) \
348 (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY)
349
350 #define PSA_ALG_DSA_BASE ((psa_algorithm_t) 0x06000400)
351 /** DSA signature with hashing.
352 *
353 * This is the signature scheme defined by FIPS 186-4,
354 * with a random per-message secret number (*k*).
355 *
356 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
357 * #PSA_ALG_IS_HASH(\p hash_alg) is true).
358 * This includes #PSA_ALG_ANY_HASH
359 * when specifying the algorithm in a usage policy.
360 *
361 * \return The corresponding DSA signature algorithm.
362 * \return Unspecified if \p hash_alg is not a supported
363 * hash algorithm.
364 */
365 #define PSA_ALG_DSA(hash_alg) \
366 (PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
367 #define PSA_ALG_DETERMINISTIC_DSA_BASE ((psa_algorithm_t) 0x06000500)
368 #define PSA_ALG_DSA_DETERMINISTIC_FLAG PSA_ALG_ECDSA_DETERMINISTIC_FLAG
369 /** Deterministic DSA signature with hashing.
370 *
371 * This is the deterministic variant defined by RFC 6979 of
372 * the signature scheme defined by FIPS 186-4.
373 *
374 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
375 * #PSA_ALG_IS_HASH(\p hash_alg) is true).
376 * This includes #PSA_ALG_ANY_HASH
377 * when specifying the algorithm in a usage policy.
378 *
379 * \return The corresponding DSA signature algorithm.
380 * \return Unspecified if \p hash_alg is not a supported
381 * hash algorithm.
382 */
383 #define PSA_ALG_DETERMINISTIC_DSA(hash_alg) \
384 (PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
385 #define PSA_ALG_IS_DSA(alg) \
386 (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) == \
387 PSA_ALG_DSA_BASE)
388 #define PSA_ALG_DSA_IS_DETERMINISTIC(alg) \
389 (((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0)
390 #define PSA_ALG_IS_DETERMINISTIC_DSA(alg) \
391 (PSA_ALG_IS_DSA(alg) && PSA_ALG_DSA_IS_DETERMINISTIC(alg))
392 #define PSA_ALG_IS_RANDOMIZED_DSA(alg) \
393 (PSA_ALG_IS_DSA(alg) && !PSA_ALG_DSA_IS_DETERMINISTIC(alg))
394
395
396 /* We need to expand the sample definition of this macro from
397 * the API definition. */
398 #undef PSA_ALG_IS_VENDOR_HASH_AND_SIGN
399 #define PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg) \
400 PSA_ALG_IS_DSA(alg)
401
402 /**@}*/
403
404 /** \addtogroup attributes
405 * @{
406 */
407
408 /** Custom Diffie-Hellman group.
409 *
410 * For keys of type #PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_FAMILY_CUSTOM) or
411 * #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_FAMILY_CUSTOM), the group data comes
412 * from domain parameters set by psa_set_key_domain_parameters().
413 */
414 #define PSA_DH_FAMILY_CUSTOM ((psa_dh_family_t) 0x7e)
415
416
417 /**
418 * \brief Set domain parameters for a key.
419 *
420 * Some key types require additional domain parameters in addition to
421 * the key type identifier and the key size. Use this function instead
422 * of psa_set_key_type() when you need to specify domain parameters.
423 *
424 * The format for the required domain parameters varies based on the key type.
425 *
426 * - For RSA keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY or #PSA_KEY_TYPE_RSA_KEY_PAIR),
427 * the domain parameter data consists of the public exponent,
428 * represented as a big-endian integer with no leading zeros.
429 * This information is used when generating an RSA key pair.
430 * When importing a key, the public exponent is read from the imported
431 * key data and the exponent recorded in the attribute structure is ignored.
432 * As an exception, the public exponent 65537 is represented by an empty
433 * byte string.
434 * - For DSA keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY or #PSA_KEY_TYPE_DSA_KEY_PAIR),
435 * the `Dss-Params` format as defined by RFC 3279 §2.3.2.
436 * ```
437 * Dss-Params ::= SEQUENCE {
438 * p INTEGER,
439 * q INTEGER,
440 * g INTEGER
441 * }
442 * ```
443 * - For Diffie-Hellman key exchange keys
444 * (#PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_FAMILY_CUSTOM) or
445 * #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_FAMILY_CUSTOM)), the
446 * `DomainParameters` format as defined by RFC 3279 §2.3.3.
447 * ```
448 * DomainParameters ::= SEQUENCE {
449 * p INTEGER, -- odd prime, p=jq +1
450 * g INTEGER, -- generator, g
451 * q INTEGER, -- factor of p-1
452 * j INTEGER OPTIONAL, -- subgroup factor
453 * validationParams ValidationParams OPTIONAL
454 * }
455 * ValidationParams ::= SEQUENCE {
456 * seed BIT STRING,
457 * pgenCounter INTEGER
458 * }
459 * ```
460 *
461 * \note This function may allocate memory or other resources.
462 * Once you have called this function on an attribute structure,
463 * you must call psa_reset_key_attributes() to free these resources.
464 *
465 * \note This is an experimental extension to the interface. It may change
466 * in future versions of the library.
467 *
468 * \param[in,out] attributes Attribute structure where the specified domain
469 * parameters will be stored.
470 * If this function fails, the content of
471 * \p attributes is not modified.
472 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
473 * \param[in] data Buffer containing the key domain parameters.
474 * The content of this buffer is interpreted
475 * according to \p type as described above.
476 * \param data_length Size of the \p data buffer in bytes.
477 *
478 * \retval #PSA_SUCCESS \emptydescription
479 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
480 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
481 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
482 */
483 psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes,
484 psa_key_type_t type,
485 const uint8_t *data,
486 size_t data_length);
487
488 /**
489 * \brief Get domain parameters for a key.
490 *
491 * Get the domain parameters for a key with this function, if any. The format
492 * of the domain parameters written to \p data is specified in the
493 * documentation for psa_set_key_domain_parameters().
494 *
495 * \note This is an experimental extension to the interface. It may change
496 * in future versions of the library.
497 *
498 * \param[in] attributes The key attribute structure to query.
499 * \param[out] data On success, the key domain parameters.
500 * \param data_size Size of the \p data buffer in bytes.
501 * The buffer is guaranteed to be large
502 * enough if its size in bytes is at least
503 * the value given by
504 * PSA_KEY_DOMAIN_PARAMETERS_SIZE().
505 * \param[out] data_length On success, the number of bytes
506 * that make up the key domain parameters data.
507 *
508 * \retval #PSA_SUCCESS \emptydescription
509 * \retval #PSA_ERROR_BUFFER_TOO_SMALL \emptydescription
510 */
511 psa_status_t psa_get_key_domain_parameters(
512 const psa_key_attributes_t *attributes,
513 uint8_t *data,
514 size_t data_size,
515 size_t *data_length);
516
517 /** Safe output buffer size for psa_get_key_domain_parameters().
518 *
519 * This macro returns a compile-time constant if its arguments are
520 * compile-time constants.
521 *
522 * \warning This function may call its arguments multiple times or
523 * zero times, so you should not pass arguments that contain
524 * side effects.
525 *
526 * \note This is an experimental extension to the interface. It may change
527 * in future versions of the library.
528 *
529 * \param key_type A supported key type.
530 * \param key_bits The size of the key in bits.
531 *
532 * \return If the parameters are valid and supported, return
533 * a buffer size in bytes that guarantees that
534 * psa_get_key_domain_parameters() will not fail with
535 * #PSA_ERROR_BUFFER_TOO_SMALL.
536 * If the parameters are a valid combination that is not supported
537 * by the implementation, this macro shall return either a
538 * sensible size or 0.
539 * If the parameters are not valid, the
540 * return value is unspecified.
541 */
542 #define PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits) \
543 (PSA_KEY_TYPE_IS_RSA(key_type) ? sizeof(int) : \
544 PSA_KEY_TYPE_IS_DH(key_type) ? PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
545 PSA_KEY_TYPE_IS_DSA(key_type) ? PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
546 0)
547 #define PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) \
548 (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 3 /*without optional parts*/)
549 #define PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) \
550 (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 2 /*p, g*/ + 34 /*q*/)
551
552 /**@}*/
553
554 /** \defgroup psa_tls_helpers TLS helper functions
555 * @{
556 */
557
558 #if defined(MBEDTLS_ECP_C)
559 #include <mbedtls/ecp.h>
560
561 /** Convert an ECC curve identifier from the Mbed TLS encoding to PSA.
562 *
563 * \note This function is provided solely for the convenience of
564 * Mbed TLS and may be removed at any time without notice.
565 *
566 * \param grpid An Mbed TLS elliptic curve identifier
567 * (`MBEDTLS_ECP_DP_xxx`).
568 * \param[out] bits On success, the bit size of the curve.
569 *
570 * \return The corresponding PSA elliptic curve identifier
571 * (`PSA_ECC_FAMILY_xxx`).
572 * \return \c 0 on failure (\p grpid is not recognized).
573 */
mbedtls_ecc_group_to_psa(mbedtls_ecp_group_id grpid,size_t * bits)574 static inline psa_ecc_family_t mbedtls_ecc_group_to_psa(mbedtls_ecp_group_id grpid,
575 size_t *bits)
576 {
577 switch (grpid) {
578 case MBEDTLS_ECP_DP_SECP192R1:
579 *bits = 192;
580 return PSA_ECC_FAMILY_SECP_R1;
581 case MBEDTLS_ECP_DP_SECP224R1:
582 *bits = 224;
583 return PSA_ECC_FAMILY_SECP_R1;
584 case MBEDTLS_ECP_DP_SECP256R1:
585 *bits = 256;
586 return PSA_ECC_FAMILY_SECP_R1;
587 case MBEDTLS_ECP_DP_SECP384R1:
588 *bits = 384;
589 return PSA_ECC_FAMILY_SECP_R1;
590 case MBEDTLS_ECP_DP_SECP521R1:
591 *bits = 521;
592 return PSA_ECC_FAMILY_SECP_R1;
593 case MBEDTLS_ECP_DP_BP256R1:
594 *bits = 256;
595 return PSA_ECC_FAMILY_BRAINPOOL_P_R1;
596 case MBEDTLS_ECP_DP_BP384R1:
597 *bits = 384;
598 return PSA_ECC_FAMILY_BRAINPOOL_P_R1;
599 case MBEDTLS_ECP_DP_BP512R1:
600 *bits = 512;
601 return PSA_ECC_FAMILY_BRAINPOOL_P_R1;
602 case MBEDTLS_ECP_DP_CURVE25519:
603 *bits = 255;
604 return PSA_ECC_FAMILY_MONTGOMERY;
605 case MBEDTLS_ECP_DP_SECP192K1:
606 *bits = 192;
607 return PSA_ECC_FAMILY_SECP_K1;
608 case MBEDTLS_ECP_DP_SECP224K1:
609 *bits = 224;
610 return PSA_ECC_FAMILY_SECP_K1;
611 case MBEDTLS_ECP_DP_SECP256K1:
612 *bits = 256;
613 return PSA_ECC_FAMILY_SECP_K1;
614 case MBEDTLS_ECP_DP_CURVE448:
615 *bits = 448;
616 return PSA_ECC_FAMILY_MONTGOMERY;
617 default:
618 *bits = 0;
619 return 0;
620 }
621 }
622
623 /** Convert an ECC curve identifier from the PSA encoding to Mbed TLS.
624 *
625 * \note This function is provided solely for the convenience of
626 * Mbed TLS and may be removed at any time without notice.
627 *
628 * \param curve A PSA elliptic curve identifier
629 * (`PSA_ECC_FAMILY_xxx`).
630 * \param bits The bit-length of a private key on \p curve.
631 * \param bits_is_sloppy If true, \p bits may be the bit-length rounded up
632 * to the nearest multiple of 8. This allows the caller
633 * to infer the exact curve from the length of a key
634 * which is supplied as a byte string.
635 *
636 * \return The corresponding Mbed TLS elliptic curve identifier
637 * (`MBEDTLS_ECP_DP_xxx`).
638 * \return #MBEDTLS_ECP_DP_NONE if \c curve is not recognized.
639 * \return #MBEDTLS_ECP_DP_NONE if \p bits is not
640 * correct for \p curve.
641 */
642 mbedtls_ecp_group_id mbedtls_ecc_group_of_psa(psa_ecc_family_t curve,
643 size_t bits,
644 int bits_is_sloppy);
645 #endif /* MBEDTLS_ECP_C */
646
647 /**@}*/
648
649 /** \defgroup psa_external_rng External random generator
650 * @{
651 */
652
653 #if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
654 /** External random generator function, implemented by the platform.
655 *
656 * When the compile-time option #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled,
657 * this function replaces Mbed TLS's entropy and DRBG modules for all
658 * random generation triggered via PSA crypto interfaces.
659 *
660 * \note This random generator must deliver random numbers with cryptographic
661 * quality and high performance. It must supply unpredictable numbers
662 * with a uniform distribution. The implementation of this function
663 * is responsible for ensuring that the random generator is seeded
664 * with sufficient entropy. If you have a hardware TRNG which is slow
665 * or delivers non-uniform output, declare it as an entropy source
666 * with mbedtls_entropy_add_source() instead of enabling this option.
667 *
668 * \param[in,out] context Pointer to the random generator context.
669 * This is all-bits-zero on the first call
670 * and preserved between successive calls.
671 * \param[out] output Output buffer. On success, this buffer
672 * contains random data with a uniform
673 * distribution.
674 * \param output_size The size of the \p output buffer in bytes.
675 * \param[out] output_length On success, set this value to \p output_size.
676 *
677 * \retval #PSA_SUCCESS
678 * Success. The output buffer contains \p output_size bytes of
679 * cryptographic-quality random data, and \c *output_length is
680 * set to \p output_size.
681 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
682 * The random generator requires extra entropy and there is no
683 * way to obtain entropy under current environment conditions.
684 * This error should not happen under normal circumstances since
685 * this function is responsible for obtaining as much entropy as
686 * it needs. However implementations of this function may return
687 * #PSA_ERROR_INSUFFICIENT_ENTROPY if there is no way to obtain
688 * entropy without blocking indefinitely.
689 * \retval #PSA_ERROR_HARDWARE_FAILURE
690 * A failure of the random generator hardware that isn't covered
691 * by #PSA_ERROR_INSUFFICIENT_ENTROPY.
692 */
693 psa_status_t mbedtls_psa_external_get_random(
694 mbedtls_psa_external_random_context_t *context,
695 uint8_t *output, size_t output_size, size_t *output_length);
696 #endif /* MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */
697
698 /**@}*/
699
700 /** \defgroup psa_builtin_keys Built-in keys
701 * @{
702 */
703
704 /** The minimum value for a key identifier that is built into the
705 * implementation.
706 *
707 * The range of key identifiers from #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN
708 * to #MBEDTLS_PSA_KEY_ID_BUILTIN_MAX within the range from
709 * #PSA_KEY_ID_VENDOR_MIN and #PSA_KEY_ID_VENDOR_MAX and must not intersect
710 * with any other set of implementation-chosen key identifiers.
711 *
712 * This value is part of the library's ABI since changing it would invalidate
713 * the values of built-in key identifiers in applications.
714 */
715 #define MBEDTLS_PSA_KEY_ID_BUILTIN_MIN ((psa_key_id_t) 0x7fff0000)
716
717 /** The maximum value for a key identifier that is built into the
718 * implementation.
719 *
720 * See #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN for more information.
721 */
722 #define MBEDTLS_PSA_KEY_ID_BUILTIN_MAX ((psa_key_id_t) 0x7fffefff)
723
724 /** A slot number identifying a key in a driver.
725 *
726 * Values of this type are used to identify built-in keys.
727 */
728 typedef uint64_t psa_drv_slot_number_t;
729
730 #if defined(MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS)
731 /** Test whether a key identifier belongs to the builtin key range.
732 *
733 * \param key_id Key identifier to test.
734 *
735 * \retval 1
736 * The key identifier is a builtin key identifier.
737 * \retval 0
738 * The key identifier is not a builtin key identifier.
739 */
psa_key_id_is_builtin(psa_key_id_t key_id)740 static inline int psa_key_id_is_builtin(psa_key_id_t key_id)
741 {
742 return (key_id >= MBEDTLS_PSA_KEY_ID_BUILTIN_MIN) &&
743 (key_id <= MBEDTLS_PSA_KEY_ID_BUILTIN_MAX);
744 }
745
746 /** Platform function to obtain the location and slot number of a built-in key.
747 *
748 * An application-specific implementation of this function must be provided if
749 * #MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS is enabled. This would typically be provided
750 * as part of a platform's system image.
751 *
752 * #MBEDTLS_SVC_KEY_ID_GET_KEY_ID(\p key_id) needs to be in the range from
753 * #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN to #MBEDTLS_PSA_KEY_ID_BUILTIN_MAX.
754 *
755 * In a multi-application configuration
756 * (\c MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER is defined),
757 * this function should check that #MBEDTLS_SVC_KEY_ID_GET_OWNER_ID(\p key_id)
758 * is allowed to use the given key.
759 *
760 * \param key_id The key ID for which to retrieve the
761 * location and slot attributes.
762 * \param[out] lifetime On success, the lifetime associated with the key
763 * corresponding to \p key_id. Lifetime is a
764 * combination of which driver contains the key,
765 * and with what persistence level the key is
766 * intended to be used. If the platform
767 * implementation does not contain specific
768 * information about the intended key persistence
769 * level, the persistence level may be reported as
770 * #PSA_KEY_PERSISTENCE_DEFAULT.
771 * \param[out] slot_number On success, the slot number known to the driver
772 * registered at the lifetime location reported
773 * through \p lifetime which corresponds to the
774 * requested built-in key.
775 *
776 * \retval #PSA_SUCCESS
777 * The requested key identifier designates a built-in key.
778 * In a multi-application configuration, the requested owner
779 * is allowed to access it.
780 * \retval #PSA_ERROR_DOES_NOT_EXIST
781 * The requested key identifier is not a built-in key which is known
782 * to this function. If a key exists in the key storage with this
783 * identifier, the data from the storage will be used.
784 * \return (any other error)
785 * Any other error is propagated to the function that requested the key.
786 * Common errors include:
787 * - #PSA_ERROR_NOT_PERMITTED: the key exists but the requested owner
788 * is not allowed to access it.
789 */
790 psa_status_t mbedtls_psa_platform_get_builtin_key(
791 mbedtls_svc_key_id_t key_id,
792 psa_key_lifetime_t *lifetime,
793 psa_drv_slot_number_t *slot_number);
794 #endif /* MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS */
795
796 /** @} */
797
798 #ifdef __cplusplus
799 }
800 #endif
801
802 #endif /* PSA_CRYPTO_EXTRA_H */
803