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