1 /** 2 * \file psa_util.h 3 * 4 * \brief Utility functions for the use of the PSA Crypto library. 5 */ 6 /* 7 * Copyright The Mbed TLS Contributors 8 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 9 */ 10 11 #ifndef MBEDTLS_PSA_UTIL_H 12 #define MBEDTLS_PSA_UTIL_H 13 #include "mbedtls/private_access.h" 14 15 #include "mbedtls/build_info.h" 16 17 #include "psa/crypto.h" 18 19 #if defined(MBEDTLS_PSA_CRYPTO_C) 20 21 /* Expose whatever RNG the PSA subsystem uses to applications using the 22 * mbedtls_xxx API. The declarations and definitions here need to be 23 * consistent with the implementation in library/psa_crypto_random_impl.h. 24 * See that file for implementation documentation. */ 25 26 27 /* The type of a `f_rng` random generator function that many library functions 28 * take. 29 * 30 * This type name is not part of the Mbed TLS stable API. It may be renamed 31 * or moved without warning. 32 */ 33 typedef int mbedtls_f_rng_t(void *p_rng, unsigned char *output, size_t output_size); 34 35 #if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) 36 37 /** The random generator function for the PSA subsystem. 38 * 39 * This function is suitable as the `f_rng` random generator function 40 * parameter of many `mbedtls_xxx` functions. Use #MBEDTLS_PSA_RANDOM_STATE 41 * to obtain the \p p_rng parameter. 42 * 43 * The implementation of this function depends on the configuration of the 44 * library. 45 * 46 * \note Depending on the configuration, this may be a function or 47 * a pointer to a function. 48 * 49 * \note This function may only be used if the PSA crypto subsystem is active. 50 * This means that you must call psa_crypto_init() before any call to 51 * this function, and you must not call this function after calling 52 * mbedtls_psa_crypto_free(). 53 * 54 * \param p_rng The random generator context. This must be 55 * #MBEDTLS_PSA_RANDOM_STATE. No other state is 56 * supported. 57 * \param output The buffer to fill. It must have room for 58 * \c output_size bytes. 59 * \param output_size The number of bytes to write to \p output. 60 * This function may fail if \p output_size is too 61 * large. It is guaranteed to accept any output size 62 * requested by Mbed TLS library functions. The 63 * maximum request size depends on the library 64 * configuration. 65 * 66 * \return \c 0 on success. 67 * \return An `MBEDTLS_ERR_ENTROPY_xxx`, 68 * `MBEDTLS_ERR_PLATFORM_xxx, 69 * `MBEDTLS_ERR_CTR_DRBG_xxx` or 70 * `MBEDTLS_ERR_HMAC_DRBG_xxx` on error. 71 */ 72 int mbedtls_psa_get_random(void *p_rng, 73 unsigned char *output, 74 size_t output_size); 75 76 /** The random generator state for the PSA subsystem. 77 * 78 * This macro expands to an expression which is suitable as the `p_rng` 79 * random generator state parameter of many `mbedtls_xxx` functions. 80 * It must be used in combination with the random generator function 81 * mbedtls_psa_get_random(). 82 * 83 * The implementation of this macro depends on the configuration of the 84 * library. Do not make any assumption on its nature. 85 */ 86 #define MBEDTLS_PSA_RANDOM_STATE NULL 87 88 #else /* !defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) */ 89 90 #if defined(MBEDTLS_CTR_DRBG_C) 91 #include "mbedtls/ctr_drbg.h" 92 typedef mbedtls_ctr_drbg_context mbedtls_psa_drbg_context_t; 93 static mbedtls_f_rng_t *const mbedtls_psa_get_random = mbedtls_ctr_drbg_random; 94 #elif defined(MBEDTLS_HMAC_DRBG_C) 95 #include "mbedtls/hmac_drbg.h" 96 typedef mbedtls_hmac_drbg_context mbedtls_psa_drbg_context_t; 97 static mbedtls_f_rng_t *const mbedtls_psa_get_random = mbedtls_hmac_drbg_random; 98 #endif 99 extern mbedtls_psa_drbg_context_t *const mbedtls_psa_random_state; 100 101 #define MBEDTLS_PSA_RANDOM_STATE mbedtls_psa_random_state 102 103 #endif /* !defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) */ 104 105 /** \defgroup psa_tls_helpers TLS helper functions 106 * @{ 107 */ 108 #if defined(PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY) 109 #include <mbedtls/ecp.h> 110 111 /** Convert an ECC curve identifier from the Mbed TLS encoding to PSA. 112 * 113 * \note This function is provided solely for the convenience of 114 * Mbed TLS and may be removed at any time without notice. 115 * 116 * \param grpid An Mbed TLS elliptic curve identifier 117 * (`MBEDTLS_ECP_DP_xxx`). 118 * \param[out] bits On success, the bit size of the curve. 119 * 120 * \return The corresponding PSA elliptic curve identifier 121 * (`PSA_ECC_FAMILY_xxx`). 122 * \return \c 0 on failure (\p grpid is not recognized). 123 */ 124 psa_ecc_family_t mbedtls_ecc_group_to_psa(mbedtls_ecp_group_id grpid, 125 size_t *bits); 126 127 /** Convert an ECC curve identifier from the PSA encoding to Mbed TLS. 128 * 129 * \note This function is provided solely for the convenience of 130 * Mbed TLS and may be removed at any time without notice. 131 * 132 * \param curve A PSA elliptic curve identifier 133 * (`PSA_ECC_FAMILY_xxx`). 134 * \param bits The bit-length of a private key on \p curve. 135 * \param bits_is_sloppy If true, \p bits may be the bit-length rounded up 136 * to the nearest multiple of 8. This allows the caller 137 * to infer the exact curve from the length of a key 138 * which is supplied as a byte string. 139 * 140 * \return The corresponding Mbed TLS elliptic curve identifier 141 * (`MBEDTLS_ECP_DP_xxx`). 142 * \return #MBEDTLS_ECP_DP_NONE if \c curve is not recognized. 143 * \return #MBEDTLS_ECP_DP_NONE if \p bits is not 144 * correct for \p curve. 145 */ 146 mbedtls_ecp_group_id mbedtls_ecc_group_of_psa(psa_ecc_family_t curve, 147 size_t bits, 148 int bits_is_sloppy); 149 #endif /* PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY */ 150 151 /**@}*/ 152 153 #endif /* MBEDTLS_PSA_CRYPTO_C */ 154 #endif /* MBEDTLS_PSA_UTIL_H */ 155
