1 /*
2  * Copyright (c) 2013-2014 Wind River Systems, Inc.
3  * Copyright (c) 2023 Intel Corporation
4  *
5  * SPDX-License-Identifier: Apache-2.0
6  */
7 
8 /**
9  * @file
10  * @brief Random number generator header file
11  *
12  * This header file declares prototypes for the kernel's random number
13  * generator APIs.
14  *
15  * Typically, a platform enables the appropriate source for the random
16  * number generation based on the hardware platform's capabilities or
17  * (for testing purposes only) enables the TEST_RANDOM_GENERATOR
18  * configuration option.
19  */
20 
21 #ifndef ZEPHYR_INCLUDE_RANDOM_RANDOM_H_
22 #define ZEPHYR_INCLUDE_RANDOM_RANDOM_H_
23 
24 #include <zephyr/types.h>
25 #include <stddef.h>
26 #include <zephyr/kernel.h>
27 
28 /**
29  * @brief Random Function APIs
30  * @defgroup random_api Random Function APIs
31  * @since 1.0
32  * @version 1.0.0
33  * @ingroup crypto
34  * @{
35  */
36 
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40 
41 
42 /**
43  * @brief Fill the destination buffer with random data values that should
44  * pass general randomness tests.
45  *
46  * @note The random values returned are not considered cryptographically
47  * secure random number values.
48  *
49  * @param [out] dst destination buffer to fill with random data.
50  * @param len size of the destination buffer.
51  *
52  */
53 __syscall void sys_rand_get(void *dst, size_t len);
54 
55 /**
56  * @brief Fill the destination buffer with cryptographically secure
57  * random data values.
58  *
59  * @note If the random values requested do not need to be cryptographically
60  * secure then use sys_rand_get() instead.
61  *
62  * @param [out] dst destination buffer to fill.
63  * @param len size of the destination buffer.
64  *
65  * @return 0 if success, -EIO if entropy reseed error
66  *
67  */
68 __syscall int sys_csrand_get(void *dst, size_t len);
69 
70 /**
71  * @brief Return a 8-bit random value that should pass general
72  * randomness tests.
73  *
74  * @note The random value returned is not a cryptographically secure
75  * random number value.
76  *
77  * @return 8-bit random value.
78  */
sys_rand8_get(void)79 static inline uint8_t sys_rand8_get(void)
80 {
81 	uint8_t ret;
82 
83 	sys_rand_get(&ret, sizeof(ret));
84 
85 	return ret;
86 }
87 
88 /**
89  * @brief Return a 16-bit random value that should pass general
90  * randomness tests.
91  *
92  * @note The random value returned is not a cryptographically secure
93  * random number value.
94  *
95  * @return 16-bit random value.
96  */
sys_rand16_get(void)97 static inline uint16_t sys_rand16_get(void)
98 {
99 	uint16_t ret;
100 
101 	sys_rand_get(&ret, sizeof(ret));
102 
103 	return ret;
104 }
105 
106 /**
107  * @brief Return a 32-bit random value that should pass general
108  * randomness tests.
109  *
110  * @note The random value returned is not a cryptographically secure
111  * random number value.
112  *
113  * @return 32-bit random value.
114  */
sys_rand32_get(void)115 static inline uint32_t sys_rand32_get(void)
116 {
117 	uint32_t ret;
118 
119 	sys_rand_get(&ret, sizeof(ret));
120 
121 	return ret;
122 }
123 
124 /**
125  * @brief Return a 64-bit random value that should pass general
126  * randomness tests.
127  *
128  * @note The random value returned is not a cryptographically secure
129  * random number value.
130  *
131  * @return 64-bit random value.
132  */
sys_rand64_get(void)133 static inline uint64_t sys_rand64_get(void)
134 {
135 	uint64_t ret;
136 
137 	sys_rand_get(&ret, sizeof(ret));
138 
139 	return ret;
140 }
141 
142 #ifdef __cplusplus
143 }
144 #endif
145 
146 /**
147  * @}
148  */
149 
150 #include <zephyr/syscalls/random.h>
151 #endif /* ZEPHYR_INCLUDE_RANDOM_RANDOM_H_ */
152