1 /**
2 * \file psa/crypto_extra.h
3 *
4 * \brief PSA cryptography module: Mbed TLS vendor extensions
5 *
6 * \note This file may not be included directly. Applications must
7 * include psa/crypto.h.
8 *
9 * This file is reserved for vendor-specific definitions.
10 */
11 /*
12 * Copyright The Mbed TLS Contributors
13 * SPDX-License-Identifier: Apache-2.0
14 *
15 * Licensed under the Apache License, Version 2.0 (the "License"); you may
16 * not use this file except in compliance with the License.
17 * You may obtain a copy of the License at
18 *
19 * http://www.apache.org/licenses/LICENSE-2.0
20 *
21 * Unless required by applicable law or agreed to in writing, software
22 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
23 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
24 * See the License for the specific language governing permissions and
25 * limitations under the License.
26 */
27
28 #ifndef PSA_CRYPTO_EXTRA_H
29 #define PSA_CRYPTO_EXTRA_H
30
31 #include "mbedtls/platform_util.h"
32
33 #include "crypto_compat.h"
34
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38
39 /* UID for secure storage seed */
40 #define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
41
42
43 /** \addtogroup attributes
44 * @{
45 */
46
47 /** \brief Declare the enrollment algorithm for a key.
48 *
49 * An operation on a key may indifferently use the algorithm set with
50 * psa_set_key_algorithm() or with this function.
51 *
52 * \param[out] attributes The attribute structure to write to.
53 * \param alg2 A second algorithm that the key may be used
54 * for, in addition to the algorithm set with
55 * psa_set_key_algorithm().
56 *
57 * \warning Setting an enrollment algorithm is not recommended, because
58 * using the same key with different algorithms can allow some
59 * attacks based on arithmetic relations between different
60 * computations made with the same key, or can escalate harmless
61 * side channels into exploitable ones. Use this function only
62 * if it is necessary to support a protocol for which it has been
63 * verified that the usage of the key with multiple algorithms
64 * is safe.
65 */
psa_set_key_enrollment_algorithm(psa_key_attributes_t * attributes,psa_algorithm_t alg2)66 static inline void psa_set_key_enrollment_algorithm(
67 psa_key_attributes_t *attributes,
68 psa_algorithm_t alg2)
69 {
70 attributes->core.policy.alg2 = alg2;
71 }
72
73 /** Retrieve the enrollment algorithm policy from key attributes.
74 *
75 * \param[in] attributes The key attribute structure to query.
76 *
77 * \return The enrollment algorithm stored in the attribute structure.
78 */
psa_get_key_enrollment_algorithm(const psa_key_attributes_t * attributes)79 static inline psa_algorithm_t psa_get_key_enrollment_algorithm(
80 const psa_key_attributes_t *attributes)
81 {
82 return( attributes->core.policy.alg2 );
83 }
84
85 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
86
87 /** Retrieve the slot number where a key is stored.
88 *
89 * A slot number is only defined for keys that are stored in a secure
90 * element.
91 *
92 * This information is only useful if the secure element is not entirely
93 * managed through the PSA Cryptography API. It is up to the secure
94 * element driver to decide how PSA slot numbers map to any other interface
95 * that the secure element may have.
96 *
97 * \param[in] attributes The key attribute structure to query.
98 * \param[out] slot_number On success, the slot number containing the key.
99 *
100 * \retval #PSA_SUCCESS
101 * The key is located in a secure element, and \p *slot_number
102 * indicates the slot number that contains it.
103 * \retval #PSA_ERROR_NOT_PERMITTED
104 * The caller is not permitted to query the slot number.
105 * Mbed Crypto currently does not return this error.
106 * \retval #PSA_ERROR_INVALID_ARGUMENT
107 * The key is not located in a secure element.
108 */
109 psa_status_t psa_get_key_slot_number(
110 const psa_key_attributes_t *attributes,
111 psa_key_slot_number_t *slot_number );
112
113 /** Choose the slot number where a key is stored.
114 *
115 * This function declares a slot number in the specified attribute
116 * structure.
117 *
118 * A slot number is only meaningful for keys that are stored in a secure
119 * element. It is up to the secure element driver to decide how PSA slot
120 * numbers map to any other interface that the secure element may have.
121 *
122 * \note Setting a slot number in key attributes for a key creation can
123 * cause the following errors when creating the key:
124 * - #PSA_ERROR_NOT_SUPPORTED if the selected secure element does
125 * not support choosing a specific slot number.
126 * - #PSA_ERROR_NOT_PERMITTED if the caller is not permitted to
127 * choose slot numbers in general or to choose this specific slot.
128 * - #PSA_ERROR_INVALID_ARGUMENT if the chosen slot number is not
129 * valid in general or not valid for this specific key.
130 * - #PSA_ERROR_ALREADY_EXISTS if there is already a key in the
131 * selected slot.
132 *
133 * \param[out] attributes The attribute structure to write to.
134 * \param slot_number The slot number to set.
135 */
psa_set_key_slot_number(psa_key_attributes_t * attributes,psa_key_slot_number_t slot_number)136 static inline void psa_set_key_slot_number(
137 psa_key_attributes_t *attributes,
138 psa_key_slot_number_t slot_number )
139 {
140 attributes->core.flags |= MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
141 attributes->slot_number = slot_number;
142 }
143
144 /** Remove the slot number attribute from a key attribute structure.
145 *
146 * This function undoes the action of psa_set_key_slot_number().
147 *
148 * \param[out] attributes The attribute structure to write to.
149 */
psa_clear_key_slot_number(psa_key_attributes_t * attributes)150 static inline void psa_clear_key_slot_number(
151 psa_key_attributes_t *attributes )
152 {
153 attributes->core.flags &= ~MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
154 }
155
156 /** Register a key that is already present in a secure element.
157 *
158 * The key must be located in a secure element designated by the
159 * lifetime field in \p attributes, in the slot set with
160 * psa_set_key_slot_number() in the attribute structure.
161 * This function makes the key available through the key identifier
162 * specified in \p attributes.
163 *
164 * \param[in] attributes The attributes of the existing key.
165 *
166 * \retval #PSA_SUCCESS
167 * The key was successfully registered.
168 * Note that depending on the design of the driver, this may or may
169 * not guarantee that a key actually exists in the designated slot
170 * and is compatible with the specified attributes.
171 * \retval #PSA_ERROR_ALREADY_EXISTS
172 * There is already a key with the identifier specified in
173 * \p attributes.
174 * \retval #PSA_ERROR_NOT_SUPPORTED
175 * The secure element driver for the specified lifetime does not
176 * support registering a key.
177 * \retval #PSA_ERROR_INVALID_ARGUMENT
178 * \p attributes specifies a lifetime which is not located
179 * in a secure element.
180 * \retval #PSA_ERROR_INVALID_ARGUMENT
181 * No slot number is specified in \p attributes,
182 * or the specified slot number is not valid.
183 * \retval #PSA_ERROR_NOT_PERMITTED
184 * The caller is not authorized to register the specified key slot.
185 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
186 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
187 * \retval #PSA_ERROR_HARDWARE_FAILURE
188 * \retval #PSA_ERROR_CORRUPTION_DETECTED
189 * \retval #PSA_ERROR_BAD_STATE
190 * The library has not been previously initialized by psa_crypto_init().
191 * It is implementation-dependent whether a failure to initialize
192 * results in this error code.
193 */
194 psa_status_t mbedtls_psa_register_se_key(
195 const psa_key_attributes_t *attributes);
196
197 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */
198
199 /**@}*/
200
201 /**
202 * \brief Library deinitialization.
203 *
204 * This function clears all data associated with the PSA layer,
205 * including the whole key store.
206 *
207 * This is an Mbed TLS extension.
208 */
209 void mbedtls_psa_crypto_free( void );
210
211 /** \brief Statistics about
212 * resource consumption related to the PSA keystore.
213 *
214 * \note The content of this structure is not part of the stable API and ABI
215 * of Mbed Crypto and may change arbitrarily from version to version.
216 */
217 typedef struct mbedtls_psa_stats_s
218 {
219 /** Number of slots containing key material for a volatile key. */
220 size_t volatile_slots;
221 /** Number of slots containing key material for a key which is in
222 * internal persistent storage. */
223 size_t persistent_slots;
224 /** Number of slots containing a reference to a key in a
225 * secure element. */
226 size_t external_slots;
227 /** Number of slots which are occupied, but do not contain
228 * key material yet. */
229 size_t half_filled_slots;
230 /** Number of slots that contain cache data. */
231 size_t cache_slots;
232 /** Number of slots that are not used for anything. */
233 size_t empty_slots;
234 /** Number of slots that are locked. */
235 size_t locked_slots;
236 /** Largest key id value among open keys in internal persistent storage. */
237 psa_key_id_t max_open_internal_key_id;
238 /** Largest key id value among open keys in secure elements. */
239 psa_key_id_t max_open_external_key_id;
240 } mbedtls_psa_stats_t;
241
242 /** \brief Get statistics about
243 * resource consumption related to the PSA keystore.
244 *
245 * \note When Mbed Crypto is built as part of a service, with isolation
246 * between the application and the keystore, the service may or
247 * may not expose this function.
248 */
249 void mbedtls_psa_get_stats( mbedtls_psa_stats_t *stats );
250
251 /**
252 * \brief Inject an initial entropy seed for the random generator into
253 * secure storage.
254 *
255 * This function injects data to be used as a seed for the random generator
256 * used by the PSA Crypto implementation. On devices that lack a trusted
257 * entropy source (preferably a hardware random number generator),
258 * the Mbed PSA Crypto implementation uses this value to seed its
259 * random generator.
260 *
261 * On devices without a trusted entropy source, this function must be
262 * called exactly once in the lifetime of the device. On devices with
263 * a trusted entropy source, calling this function is optional.
264 * In all cases, this function may only be called before calling any
265 * other function in the PSA Crypto API, including psa_crypto_init().
266 *
267 * When this function returns successfully, it populates a file in
268 * persistent storage. Once the file has been created, this function
269 * can no longer succeed.
270 *
271 * If any error occurs, this function does not change the system state.
272 * You can call this function again after correcting the reason for the
273 * error if possible.
274 *
275 * \warning This function **can** fail! Callers MUST check the return status.
276 *
277 * \warning If you use this function, you should use it as part of a
278 * factory provisioning process. The value of the injected seed
279 * is critical to the security of the device. It must be
280 * *secret*, *unpredictable* and (statistically) *unique per device*.
281 * You should be generate it randomly using a cryptographically
282 * secure random generator seeded from trusted entropy sources.
283 * You should transmit it securely to the device and ensure
284 * that its value is not leaked or stored anywhere beyond the
285 * needs of transmitting it from the point of generation to
286 * the call of this function, and erase all copies of the value
287 * once this function returns.
288 *
289 * This is an Mbed TLS extension.
290 *
291 * \note This function is only available on the following platforms:
292 * * If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled.
293 * Note that you must provide compatible implementations of
294 * mbedtls_nv_seed_read and mbedtls_nv_seed_write.
295 * * In a client-server integration of PSA Cryptography, on the client side,
296 * if the server supports this feature.
297 * \param[in] seed Buffer containing the seed value to inject.
298 * \param[in] seed_size Size of the \p seed buffer.
299 * The size of the seed in bytes must be greater
300 * or equal to both #MBEDTLS_ENTROPY_MIN_PLATFORM
301 * and #MBEDTLS_ENTROPY_BLOCK_SIZE.
302 * It must be less or equal to
303 * #MBEDTLS_ENTROPY_MAX_SEED_SIZE.
304 *
305 * \retval #PSA_SUCCESS
306 * The seed value was injected successfully. The random generator
307 * of the PSA Crypto implementation is now ready for use.
308 * You may now call psa_crypto_init() and use the PSA Crypto
309 * implementation.
310 * \retval #PSA_ERROR_INVALID_ARGUMENT
311 * \p seed_size is out of range.
312 * \retval #PSA_ERROR_STORAGE_FAILURE
313 * There was a failure reading or writing from storage.
314 * \retval #PSA_ERROR_NOT_PERMITTED
315 * The library has already been initialized. It is no longer
316 * possible to call this function.
317 */
318 psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed,
319 size_t seed_size);
320
321 /** \addtogroup crypto_types
322 * @{
323 */
324
325 /** DSA public key.
326 *
327 * The import and export format is the
328 * representation of the public key `y = g^x mod p` as a big-endian byte
329 * string. The length of the byte string is the length of the base prime `p`
330 * in bytes.
331 */
332 #define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t)0x4002)
333
334 /** DSA key pair (private and public key).
335 *
336 * The import and export format is the
337 * representation of the private key `x` as a big-endian byte string. The
338 * length of the byte string is the private key size in bytes (leading zeroes
339 * are not stripped).
340 *
341 * Determinstic DSA key derivation with psa_generate_derived_key follows
342 * FIPS 186-4 §B.1.2: interpret the byte string as integer
343 * in big-endian order. Discard it if it is not in the range
344 * [0, *N* - 2] where *N* is the boundary of the private key domain
345 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
346 * or the order of the curve's base point for ECC).
347 * Add 1 to the resulting integer and use this as the private key *x*.
348 *
349 */
350 #define PSA_KEY_TYPE_DSA_KEY_PAIR ((psa_key_type_t)0x7002)
351
352 /** Whether a key type is an DSA key (pair or public-only). */
353 #define PSA_KEY_TYPE_IS_DSA(type) \
354 (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY)
355
356 #define PSA_ALG_DSA_BASE ((psa_algorithm_t)0x06000400)
357 /** DSA signature with hashing.
358 *
359 * This is the signature scheme defined by FIPS 186-4,
360 * with a random per-message secret number (*k*).
361 *
362 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
363 * #PSA_ALG_IS_HASH(\p hash_alg) is true).
364 * This includes #PSA_ALG_ANY_HASH
365 * when specifying the algorithm in a usage policy.
366 *
367 * \return The corresponding DSA signature algorithm.
368 * \return Unspecified if \p hash_alg is not a supported
369 * hash algorithm.
370 */
371 #define PSA_ALG_DSA(hash_alg) \
372 (PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
373 #define PSA_ALG_DETERMINISTIC_DSA_BASE ((psa_algorithm_t)0x06000500)
374 #define PSA_ALG_DSA_DETERMINISTIC_FLAG PSA_ALG_ECDSA_DETERMINISTIC_FLAG
375 /** Deterministic DSA signature with hashing.
376 *
377 * This is the deterministic variant defined by RFC 6979 of
378 * the signature scheme defined by FIPS 186-4.
379 *
380 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
381 * #PSA_ALG_IS_HASH(\p hash_alg) is true).
382 * This includes #PSA_ALG_ANY_HASH
383 * when specifying the algorithm in a usage policy.
384 *
385 * \return The corresponding DSA signature algorithm.
386 * \return Unspecified if \p hash_alg is not a supported
387 * hash algorithm.
388 */
389 #define PSA_ALG_DETERMINISTIC_DSA(hash_alg) \
390 (PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
391 #define PSA_ALG_IS_DSA(alg) \
392 (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) == \
393 PSA_ALG_DSA_BASE)
394 #define PSA_ALG_DSA_IS_DETERMINISTIC(alg) \
395 (((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0)
396 #define PSA_ALG_IS_DETERMINISTIC_DSA(alg) \
397 (PSA_ALG_IS_DSA(alg) && PSA_ALG_DSA_IS_DETERMINISTIC(alg))
398 #define PSA_ALG_IS_RANDOMIZED_DSA(alg) \
399 (PSA_ALG_IS_DSA(alg) && !PSA_ALG_DSA_IS_DETERMINISTIC(alg))
400
401
402 /* We need to expand the sample definition of this macro from
403 * the API definition. */
404 #undef PSA_ALG_IS_HASH_AND_SIGN
405 #define PSA_ALG_IS_HASH_AND_SIGN(alg) \
406 (PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) || \
407 PSA_ALG_IS_DSA(alg) || PSA_ALG_IS_ECDSA(alg))
408
409 /**@}*/
410
411 /** \addtogroup attributes
412 * @{
413 */
414
415 /** Custom Diffie-Hellman group.
416 *
417 * For keys of type #PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_FAMILY_CUSTOM) or
418 * #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_FAMILY_CUSTOM), the group data comes
419 * from domain parameters set by psa_set_key_domain_parameters().
420 */
421 #define PSA_DH_FAMILY_CUSTOM ((psa_dh_family_t) 0x7e)
422
423
424 /**
425 * \brief Set domain parameters for a key.
426 *
427 * Some key types require additional domain parameters in addition to
428 * the key type identifier and the key size. Use this function instead
429 * of psa_set_key_type() when you need to specify domain parameters.
430 *
431 * The format for the required domain parameters varies based on the key type.
432 *
433 * - For RSA keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY or #PSA_KEY_TYPE_RSA_KEY_PAIR),
434 * the domain parameter data consists of the public exponent,
435 * represented as a big-endian integer with no leading zeros.
436 * This information is used when generating an RSA key pair.
437 * When importing a key, the public exponent is read from the imported
438 * key data and the exponent recorded in the attribute structure is ignored.
439 * As an exception, the public exponent 65537 is represented by an empty
440 * byte string.
441 * - For DSA keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY or #PSA_KEY_TYPE_DSA_KEY_PAIR),
442 * the `Dss-Parms` format as defined by RFC 3279 §2.3.2.
443 * ```
444 * Dss-Parms ::= SEQUENCE {
445 * p INTEGER,
446 * q INTEGER,
447 * g INTEGER
448 * }
449 * ```
450 * - For Diffie-Hellman key exchange keys
451 * (#PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_FAMILY_CUSTOM) or
452 * #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_FAMILY_CUSTOM)), the
453 * `DomainParameters` format as defined by RFC 3279 §2.3.3.
454 * ```
455 * DomainParameters ::= SEQUENCE {
456 * p INTEGER, -- odd prime, p=jq +1
457 * g INTEGER, -- generator, g
458 * q INTEGER, -- factor of p-1
459 * j INTEGER OPTIONAL, -- subgroup factor
460 * validationParms ValidationParms OPTIONAL
461 * }
462 * ValidationParms ::= SEQUENCE {
463 * seed BIT STRING,
464 * pgenCounter INTEGER
465 * }
466 * ```
467 *
468 * \note This function may allocate memory or other resources.
469 * Once you have called this function on an attribute structure,
470 * you must call psa_reset_key_attributes() to free these resources.
471 *
472 * \note This is an experimental extension to the interface. It may change
473 * in future versions of the library.
474 *
475 * \param[in,out] attributes Attribute structure where the specified domain
476 * parameters will be stored.
477 * If this function fails, the content of
478 * \p attributes is not modified.
479 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
480 * \param[in] data Buffer containing the key domain parameters.
481 * The content of this buffer is interpreted
482 * according to \p type as described above.
483 * \param data_length Size of the \p data buffer in bytes.
484 *
485 * \retval #PSA_SUCCESS
486 * \retval #PSA_ERROR_INVALID_ARGUMENT
487 * \retval #PSA_ERROR_NOT_SUPPORTED
488 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
489 */
490 psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes,
491 psa_key_type_t type,
492 const uint8_t *data,
493 size_t data_length);
494
495 /**
496 * \brief Get domain parameters for a key.
497 *
498 * Get the domain parameters for a key with this function, if any. The format
499 * of the domain parameters written to \p data is specified in the
500 * documentation for psa_set_key_domain_parameters().
501 *
502 * \note This is an experimental extension to the interface. It may change
503 * in future versions of the library.
504 *
505 * \param[in] attributes The key attribute structure to query.
506 * \param[out] data On success, the key domain parameters.
507 * \param data_size Size of the \p data buffer in bytes.
508 * The buffer is guaranteed to be large
509 * enough if its size in bytes is at least
510 * the value given by
511 * PSA_KEY_DOMAIN_PARAMETERS_SIZE().
512 * \param[out] data_length On success, the number of bytes
513 * that make up the key domain parameters data.
514 *
515 * \retval #PSA_SUCCESS
516 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
517 */
518 psa_status_t psa_get_key_domain_parameters(
519 const psa_key_attributes_t *attributes,
520 uint8_t *data,
521 size_t data_size,
522 size_t *data_length);
523
524 /** Safe output buffer size for psa_get_key_domain_parameters().
525 *
526 * This macro returns a compile-time constant if its arguments are
527 * compile-time constants.
528 *
529 * \warning This function may call its arguments multiple times or
530 * zero times, so you should not pass arguments that contain
531 * side effects.
532 *
533 * \note This is an experimental extension to the interface. It may change
534 * in future versions of the library.
535 *
536 * \param key_type A supported key type.
537 * \param key_bits The size of the key in bits.
538 *
539 * \return If the parameters are valid and supported, return
540 * a buffer size in bytes that guarantees that
541 * psa_get_key_domain_parameters() will not fail with
542 * #PSA_ERROR_BUFFER_TOO_SMALL.
543 * If the parameters are a valid combination that is not supported
544 * by the implementation, this macro shall return either a
545 * sensible size or 0.
546 * If the parameters are not valid, the
547 * return value is unspecified.
548 */
549 #define PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits) \
550 (PSA_KEY_TYPE_IS_RSA(key_type) ? sizeof(int) : \
551 PSA_KEY_TYPE_IS_DH(key_type) ? PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
552 PSA_KEY_TYPE_IS_DSA(key_type) ? PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
553 0)
554 #define PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) \
555 (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 3 /*without optional parts*/)
556 #define PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) \
557 (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 2 /*p, g*/ + 34 /*q*/)
558
559 /**@}*/
560
561 /** \defgroup psa_tls_helpers TLS helper functions
562 * @{
563 */
564
565 #if defined(MBEDTLS_ECP_C)
566 #include <mbedtls/ecp.h>
567
568 /** Convert an ECC curve identifier from the Mbed TLS encoding to PSA.
569 *
570 * \note This function is provided solely for the convenience of
571 * Mbed TLS and may be removed at any time without notice.
572 *
573 * \param grpid An Mbed TLS elliptic curve identifier
574 * (`MBEDTLS_ECP_DP_xxx`).
575 * \param[out] bits On success, the bit size of the curve.
576 *
577 * \return The corresponding PSA elliptic curve identifier
578 * (`PSA_ECC_FAMILY_xxx`).
579 * \return \c 0 on failure (\p grpid is not recognized).
580 */
mbedtls_ecc_group_to_psa(mbedtls_ecp_group_id grpid,size_t * bits)581 static inline psa_ecc_family_t mbedtls_ecc_group_to_psa( mbedtls_ecp_group_id grpid,
582 size_t *bits )
583 {
584 switch( grpid )
585 {
586 case MBEDTLS_ECP_DP_SECP192R1:
587 *bits = 192;
588 return( PSA_ECC_FAMILY_SECP_R1 );
589 case MBEDTLS_ECP_DP_SECP224R1:
590 *bits = 224;
591 return( PSA_ECC_FAMILY_SECP_R1 );
592 case MBEDTLS_ECP_DP_SECP256R1:
593 *bits = 256;
594 return( PSA_ECC_FAMILY_SECP_R1 );
595 case MBEDTLS_ECP_DP_SECP384R1:
596 *bits = 384;
597 return( PSA_ECC_FAMILY_SECP_R1 );
598 case MBEDTLS_ECP_DP_SECP521R1:
599 *bits = 521;
600 return( PSA_ECC_FAMILY_SECP_R1 );
601 case MBEDTLS_ECP_DP_BP256R1:
602 *bits = 256;
603 return( PSA_ECC_FAMILY_BRAINPOOL_P_R1 );
604 case MBEDTLS_ECP_DP_BP384R1:
605 *bits = 384;
606 return( PSA_ECC_FAMILY_BRAINPOOL_P_R1 );
607 case MBEDTLS_ECP_DP_BP512R1:
608 *bits = 512;
609 return( PSA_ECC_FAMILY_BRAINPOOL_P_R1 );
610 case MBEDTLS_ECP_DP_CURVE25519:
611 *bits = 255;
612 return( PSA_ECC_FAMILY_MONTGOMERY );
613 case MBEDTLS_ECP_DP_SECP192K1:
614 *bits = 192;
615 return( PSA_ECC_FAMILY_SECP_K1 );
616 case MBEDTLS_ECP_DP_SECP224K1:
617 *bits = 224;
618 return( PSA_ECC_FAMILY_SECP_K1 );
619 case MBEDTLS_ECP_DP_SECP256K1:
620 *bits = 256;
621 return( PSA_ECC_FAMILY_SECP_K1 );
622 case MBEDTLS_ECP_DP_CURVE448:
623 *bits = 448;
624 return( PSA_ECC_FAMILY_MONTGOMERY );
625 default:
626 *bits = 0;
627 return( 0 );
628 }
629 }
630
631 /** Convert an ECC curve identifier from the PSA encoding to Mbed TLS.
632 *
633 * \note This function is provided solely for the convenience of
634 * Mbed TLS and may be removed at any time without notice.
635 *
636 * \param curve A PSA elliptic curve identifier
637 * (`PSA_ECC_FAMILY_xxx`).
638 * \param byte_length The byte-length of a private key on \p curve.
639 *
640 * \return The corresponding Mbed TLS elliptic curve identifier
641 * (`MBEDTLS_ECP_DP_xxx`).
642 * \return #MBEDTLS_ECP_DP_NONE if \c curve is not recognized.
643 * \return #MBEDTLS_ECP_DP_NONE if \p byte_length is not
644 * correct for \p curve.
645 */
646 mbedtls_ecp_group_id mbedtls_ecc_group_of_psa( psa_ecc_family_t curve,
647 size_t byte_length );
648 #endif /* MBEDTLS_ECP_C */
649
650 /**@}*/
651
652 #ifdef __cplusplus
653 }
654 #endif
655
656 #endif /* PSA_CRYPTO_EXTRA_H */
657
