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