1 /* 2 * Copyright (c) 2021-2023, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 /** ============================================================================ 33 * @file RNGLPF3RF.h 34 * 35 * @brief RNG driver implementation for the CC23X0 family 36 * 37 * This file should only be included in the board file to fill the RNG_config 38 * structure. 39 * 40 * The CC23X0 family does not have a general purpose TRNG. However, it can 41 * collect radio noise when the radio is not being used (such as during boot) 42 * and use that noise as a source for a seed for an AES CTR DRBG. 43 * 44 * The radio noise is first processed using AES CBC MAC in order to compress 45 * the entropy of the noise into a 256 bit value with close to 256 bits of 46 * entropy. That 256 bit value is then used as the seed value for the AES CTR 47 * DRBG. 48 * 49 * The RNG driver then uses the AES CTR DRBG to fulfill any requests for 50 * entropy. 51 * 52 * In order to ensure proper operation, RNG_init() must be called prior to to 53 * any other use of the radio. Because other drivers may be using the RNG 54 * driver, it is recommended that RNG_init() be called as part of the 55 * application's startup routines. 56 * 57 * @note This implementation does not support the RNG_RETURN_BEHAVIOR_CALLBACK 58 * return mode. 59 * 60 * @note This implementation treats RNG_RETURN_BEHAVIOR_POLLING as 61 * RNG_RETURN_BEHAVIOR_BLOCKING. 62 */ 63 64 #ifndef ti_drivers_rng_RNGLPF3RF__include 65 #define ti_drivers_rng_RNGLPF3RF__include 66 67 #include <stdint.h> 68 #include <stdbool.h> 69 70 #include <ti/drivers/RNG.h> 71 72 #ifdef __cplusplus 73 extern "C" { 74 #endif 75 76 /* Word length of the noise input from RCL */ 77 extern const uint32_t RNGLPF3RF_noiseInputWordLen; 78 79 /*! \cond Internal APIs */ 80 81 /*! 82 * @brief RNGLPF3RF Object 83 * 84 * \note The application must not access any member variables of this structure! 85 */ 86 typedef struct 87 { 88 bool isOpen; 89 uint32_t timeout; 90 } RNGLPF3RF_Object; 91 92 typedef struct 93 { 94 uint8_t intPriority; 95 } RNGLPF3RF_HWAttrs; 96 97 /*! 98 * @brief Conditions the noise buffer from RCL and seed the RNG. 99 * 100 * This function conditions the provided RCL (Radio) noise 101 * using CBC MAC to generate a 256-bit seed which is used seed the RNG driver. 102 * 103 * The noise input is read from RCL using RCL_AdcNoise_get_samples_blocking(). 104 * The minimum word length of the noise input is 80 words to generate a 256-bit seed. 105 * The user must ensure #RNGLPF3RF_conditionNoiseToGenerateSeed() is called before #RNG_init(), otherwise 106 * RNG driver initialization will fail. 107 * 108 * @param noisePtr A pointer to the buffer containing noise input from RCL 109 * 110 * @retval #RNG_STATUS_SUCCESS RNG driver was successfully seeded. 111 * @retval #RNG_STATUS_NOISE_INPUT_INVALID RNG driver was not seeded as the noise input was invalid 112 */ 113 int_fast16_t RNGLPF3RF_conditionNoiseToGenerateSeed(uint32_t *noisePtr); 114 115 /*! \endcond */ 116 117 #ifdef __cplusplus 118 } 119 #endif 120 121 #endif /* ti_drivers_rng_RNGLPF3RF__include */ 122
