1 /*
2  * Copyright (c) 2018-2019, 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       Random.h
34  *
35  *  @brief      Interface to generate pseudo-random numbers
36  *
37  *  @warning    The numbers generated by this module are not crpytographically-secure!
38  *              Do not use this module to generate keying material or for other
39  *              security-related purposes!
40  *
41  *  This module generates non-cryptographically-secure random numbers in an
42  *  easy to use and fast way.
43  *
44  *  There is a single global state that must be initialised by calling
45  *  Random_seedAutomatic() or Random_seedManual(). Afterwards, you can call
46  *  Random_getNumber() or Random_getBytes() as desired. Both are thread-safe
47  *  and protect the internal state.
48  *
49  *  The pseudo-random number generator used is the "xorwow" algorithm specified in
50  *  Marsaglia's "Xorshift RNGs" paper. It keeps 20 bytes of state that must be
51  *  seeded and has a period of 2^160 - 2^32 before a sequence wraps.
52  *
53  *  Generating a random number with this algorithm is quite fast. Random_getNumber()
54  *  only requires 82 instructions which is 1.7us on a 48MHz Cortex M4. That includes
55  *  disabling interrupts.
56  *
57  *  @code
58  *
59  *  int_fast16_t status;
60  *  uint32_t randomNumber;
61  *
62  *  status = Random_seedAutomatic();
63  *
64  *  if (status != Random_STATUS_SUCCESS) {
65  *       while(1);
66  *  }
67  *
68  *  randomNumber = Random_getNumber();
69  *
70  *  @endcode
71  *
72  *
73  */
74 
75 #ifndef ti_drivers_utils_Random__include
76 #define ti_drivers_utils_Random__include
77 
78 #include <stdint.h>
79 #include <stdbool.h>
80 #include <stddef.h>
81 
82 #ifdef __cplusplus
83 extern "C" {
84 #endif
85 
86 #define Random_STATUS_SUCCESS   (0)
87 #define Random_STATUS_ERROR     (-1)
88 
89 /*! @brief Length of the seed in bytes */
90 #define Random_SEED_LENGTH (20)
91 
92 /**
93  *  @brief Seed internal state automatically
94  *
95  *  This function seeds or reseeds the internal state.
96  *  The method for generating the seed is device dependent.
97  *
98  *  If a TRNG is available, it will be used to generate the seed.
99  *
100  *  If a TRNG is not available, information unique to the device running
101  *  the code will be used. This may be a unique device identifier or other
102  *  information such as a MAC address.
103  *  Since the seed is constant per device for devices without a TRNG, the
104  *  number sequence will restart after each call to Random_seedAutomatic().
105  *  This will usually occur after rebooting the device.
106  *
107  *  If neither a TRNG nor a unique device identifier is available,
108  *  a constant will be used.
109  *
110  *  @return Returns a status code
111  *
112  *  @sa Random_seedManual()
113  *
114  *  @post Random_getNumber()
115  *
116  *  @post Random_getBytes()
117  */
118 extern int_fast16_t Random_seedAutomatic(void);
119 
120 /**
121  *  @brief Set the internal state to a specified seed
122  *
123  *  This function sets the internal state to the seed specified
124  *  by the application.
125  *
126  *  @param seed     Seed to set the internal state to
127  *
128  *  @sa Random_seedAutomatic()
129  *
130  *  @post Random_getNumber()
131  *
132  *  @post Random_getBytes()
133  */
134 extern void Random_seedManual(uint8_t seed[Random_SEED_LENGTH]);
135 
136 /**
137  *  @brief Returns a random number
138  *
139  *  This function returns a random number and updates the
140  *  internal state.
141  *
142  *  @return Returns random number
143  *
144  *  @pre Random_seedAutomatic()
145  *  @pre Random_seedManual()
146  */
147 extern uint32_t Random_getNumber(void);
148 
149 /**
150  *  Returns a number of random bytes
151  *
152  *  This is a convenience function that fills the specified
153  *  array with random bytes by repeatedly calling Random_getNumber().
154  *
155  *  @param buffer     Buffer to fill with random bytes
156  *
157  *  @param bufferSize Size of buffer. Any value is permitted, including
158  *                    those that are not multiples of sizeof(uint32_t).
159  *
160  *  @pre Random_seedAutomatic()
161  *  @pre Random_seedManual()
162  */
163 extern void Random_getBytes(void *buffer, size_t bufferSize);
164 
165 
166 #ifdef __cplusplus
167 }
168 #endif
169 
170 #endif /* ti_drivers_utils_Random__include */
171