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 #if defined(MBEDTLS_PSA_CRYPTO_C) 18 19 /* Expose whatever RNG the PSA subsystem uses to applications using the 20 * mbedtls_xxx API. The declarations and definitions here need to be 21 * consistent with the implementation in library/psa_crypto_random_impl.h. 22 * See that file for implementation documentation. */ 23 24 25 /* The type of a `f_rng` random generator function that many library functions 26 * take. 27 * 28 * This type name is not part of the Mbed TLS stable API. It may be renamed 29 * or moved without warning. 30 */ 31 typedef int mbedtls_f_rng_t(void *p_rng, unsigned char *output, size_t output_size); 32 33 #if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) 34 35 /** The random generator function for the PSA subsystem. 36 * 37 * This function is suitable as the `f_rng` random generator function 38 * parameter of many `mbedtls_xxx` functions. Use #MBEDTLS_PSA_RANDOM_STATE 39 * to obtain the \p p_rng parameter. 40 * 41 * The implementation of this function depends on the configuration of the 42 * library. 43 * 44 * \note Depending on the configuration, this may be a function or 45 * a pointer to a function. 46 * 47 * \note This function may only be used if the PSA crypto subsystem is active. 48 * This means that you must call psa_crypto_init() before any call to 49 * this function, and you must not call this function after calling 50 * mbedtls_psa_crypto_free(). 51 * 52 * \param p_rng The random generator context. This must be 53 * #MBEDTLS_PSA_RANDOM_STATE. No other state is 54 * supported. 55 * \param output The buffer to fill. It must have room for 56 * \c output_size bytes. 57 * \param output_size The number of bytes to write to \p output. 58 * This function may fail if \p output_size is too 59 * large. It is guaranteed to accept any output size 60 * requested by Mbed TLS library functions. The 61 * maximum request size depends on the library 62 * configuration. 63 * 64 * \return \c 0 on success. 65 * \return An `MBEDTLS_ERR_ENTROPY_xxx`, 66 * `MBEDTLS_ERR_PLATFORM_xxx, 67 * `MBEDTLS_ERR_CTR_DRBG_xxx` or 68 * `MBEDTLS_ERR_HMAC_DRBG_xxx` on error. 69 */ 70 int mbedtls_psa_get_random(void *p_rng, 71 unsigned char *output, 72 size_t output_size); 73 74 /** The random generator state for the PSA subsystem. 75 * 76 * This macro expands to an expression which is suitable as the `p_rng` 77 * random generator state parameter of many `mbedtls_xxx` functions. 78 * It must be used in combination with the random generator function 79 * mbedtls_psa_get_random(). 80 * 81 * The implementation of this macro depends on the configuration of the 82 * library. Do not make any assumption on its nature. 83 */ 84 #define MBEDTLS_PSA_RANDOM_STATE NULL 85 86 #else /* !defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) */ 87 88 #if defined(MBEDTLS_CTR_DRBG_C) 89 #include "mbedtls/ctr_drbg.h" 90 typedef mbedtls_ctr_drbg_context mbedtls_psa_drbg_context_t; 91 static mbedtls_f_rng_t *const mbedtls_psa_get_random = mbedtls_ctr_drbg_random; 92 #elif defined(MBEDTLS_HMAC_DRBG_C) 93 #include "mbedtls/hmac_drbg.h" 94 typedef mbedtls_hmac_drbg_context mbedtls_psa_drbg_context_t; 95 static mbedtls_f_rng_t *const mbedtls_psa_get_random = mbedtls_hmac_drbg_random; 96 #endif 97 extern mbedtls_psa_drbg_context_t *const mbedtls_psa_random_state; 98 99 #define MBEDTLS_PSA_RANDOM_STATE mbedtls_psa_random_state 100 101 #endif /* !defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) */ 102 103 #endif /* MBEDTLS_PSA_CRYPTO_C */ 104 #endif /* MBEDTLS_PSA_UTIL_H */ 105