1 /**
2  * \file random.h
3  *
4  * \brief   This file contains the prototypes of helper functions to generate
5  *          random numbers for the purpose of testing.
6  */
7 
8 /*
9  *  Copyright The Mbed TLS Contributors
10  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
11  */
12 
13 #ifndef TEST_RANDOM_H
14 #define TEST_RANDOM_H
15 
16 #include "mbedtls/build_info.h"
17 
18 #include <stddef.h>
19 #include <stdint.h>
20 
21 typedef struct {
22     unsigned char *buf; /* Pointer to a buffer of length bytes. */
23     size_t length;
24     /* If fallback_f_rng is NULL, fail after delivering length bytes. */
25     int (*fallback_f_rng)(void *, unsigned char *, size_t);
26     void *fallback_p_rng;
27 } mbedtls_test_rnd_buf_info;
28 
29 /**
30  * Info structure for the pseudo random function
31  *
32  * Key should be set at the start to a test-unique value.
33  * Do not forget endianness!
34  * State( v0, v1 ) should be set to zero.
35  */
36 typedef struct {
37     uint32_t key[16];
38     uint32_t v0, v1;
39 } mbedtls_test_rnd_pseudo_info;
40 
41 /**
42  * This function just returns data from rand().
43  * Although predictable and often similar on multiple
44  * runs, this does not result in identical random on
45  * each run. So do not use this if the results of a
46  * test depend on the random data that is generated.
47  *
48  * rng_state shall be NULL.
49  */
50 int mbedtls_test_rnd_std_rand(void *rng_state,
51                               unsigned char *output,
52                               size_t len);
53 
54 /**
55  * This function only returns zeros.
56  *
57  * \p rng_state shall be \c NULL.
58  */
59 int mbedtls_test_rnd_zero_rand(void *rng_state,
60                                unsigned char *output,
61                                size_t len);
62 
63 /**
64  * This function returns random data based on a buffer it receives.
65  *
66  * \p rng_state shall be a pointer to a #mbedtls_test_rnd_buf_info structure.
67  *
68  * The number of bytes released from the buffer on each call to
69  * the random function is specified by \p len.
70  *
71  * After the buffer is empty, this function will call the fallback RNG in the
72  * #mbedtls_test_rnd_buf_info structure if there is one, and
73  * will return #MBEDTLS_ERR_ENTROPY_SOURCE_FAILED otherwise.
74  */
75 int mbedtls_test_rnd_buffer_rand(void *rng_state,
76                                  unsigned char *output,
77                                  size_t len);
78 
79 /**
80  * This function returns random based on a pseudo random function.
81  * This means the results should be identical on all systems.
82  * Pseudo random is based on the XTEA encryption algorithm to
83  * generate pseudorandom.
84  *
85  * \p rng_state shall be a pointer to a #mbedtls_test_rnd_pseudo_info structure.
86  */
87 int mbedtls_test_rnd_pseudo_rand(void *rng_state,
88                                  unsigned char *output,
89                                  size_t len);
90 
91 #endif /* TEST_RANDOM_H */
92