1 /* 2 * Copyright (c) 2023-2024, The TrustedFirmware-M Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 */ 7 8 #ifndef __CC3XX_PSA_RANDOM_H__ 9 #define __CC3XX_PSA_RANDOM_H__ 10 11 /** @file cc3xx_psa_random.h 12 * 13 * This file contains the declaration of the entry points associated to the 14 * random generation capability as described by the PSA Cryptoprocessor 15 * Driver interface specification 16 * 17 */ 18 19 #include "psa/crypto.h" 20 #include "cc3xx_crypto_primitives_private.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /** 27 * @brief Initializes the RNG. 28 * 29 * @note This function provides to seed itself on initialization requiring 30 * the expected amout of initial entropy from the TRNG as expected by 31 * the underlying DRBG mechanism configured at build time, before 32 * instantiating the DRBG. External initial_entropy_size property 33 * should be equal to 0. 34 * 35 * @param[out] context A pointer to a context holding state of the DRBG 36 * @return psa_status_t 37 */ 38 psa_status_t cc3xx_init_random(cc3xx_random_context_t *context); 39 40 /** 41 * @brief Injects entropy into the RNG state. 42 * 43 * @note It is currently not supported as the driver expectation is to be 44 * treated as a full RNG that seeds (and re-seeds) itself when required, 45 * without expecting the core to provide entropy. If the design changes, 46 * this function might need to be implemented 47 * 48 * @param[in,out] context A pointer to a context holding the state of the DRBG 49 * @param[in] entropy Entropy to be injected into the DRBG state 50 * @param[in] entropy_size Size in bytes of the entropy to be injected 51 * @return psa_status_t 52 */ 53 psa_status_t cc3xx_add_entropy( 54 cc3xx_random_context_t *context, 55 const uint8_t *entropy, 56 size_t entropy_size); 57 58 /** 59 * @brief Generates random numbers with a uniform distribution, according 60 * to the underlying DRBG mechanism configured at build time in the 61 * cc3xx_psa_config.h header 62 * 63 * @note This function provides to reseed itself transparently from the 64 * calle when it detects that the underlying DRBG mechanism requires 65 * reseeding. External reseed_entropy_size property should be equal 66 * to 0. 67 * 68 * @param[in,out] context A pointer to a context holding the state of the DRBG 69 * @param[out] output Buffer containing the random data collected 70 * @param[in] output_size Size in bytes of the buffer to fill 71 * @param[out] output_length Number of bytes effectively returned in \ref buffer 72 * @return psa_status_t 73 */ 74 psa_status_t cc3xx_get_random( 75 cc3xx_random_context_t *context, 76 uint8_t *output, 77 size_t output_size, 78 size_t *output_length); 79 80 #ifdef __cplusplus 81 } 82 #endif 83 84 #endif /* __CC3XX_PSA_RANDOM_H__ */ 85
