blob: 1fd3ac8e59fb17e95b5326e9a66d7fa975f1fb37 [file] [log] [blame]
Ronald Cronb7eb67f2020-06-09 16:57:42 +02001/**
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
Bence Szépkúti86974652020-06-15 11:59:37 +02008/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02009 * Copyright The Mbed TLS Contributors
Dave Rodgman7ff79652023-11-03 12:04:52 +000010 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Ronald Cronb7eb67f2020-06-09 16:57:42 +020011 */
12
13#ifndef TEST_RANDOM_H
14#define TEST_RANDOM_H
15
16#if !defined(MBEDTLS_CONFIG_FILE)
17#include "mbedtls/config.h"
18#else
19#include MBEDTLS_CONFIG_FILE
20#endif
21
Ronald Cron2058d562020-06-09 17:11:47 +020022#include <stddef.h>
23#include <stdint.h>
24
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010025typedef struct {
Gilles Peskinebef30192021-03-24 00:48:57 +010026 unsigned char *buf; /* Pointer to a buffer of length bytes. */
Ronald Cron2058d562020-06-09 17:11:47 +020027 size_t length;
Gilles Peskinebef30192021-03-24 00:48:57 +010028 /* If fallback_f_rng is NULL, fail after delivering length bytes. */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010029 int (*fallback_f_rng)(void *, unsigned char *, size_t);
Gilles Peskinebef30192021-03-24 00:48:57 +010030 void *fallback_p_rng;
Ronald Cron351f0ee2020-06-10 12:12:18 +020031} mbedtls_test_rnd_buf_info;
Ronald Cron2058d562020-06-09 17:11:47 +020032
33/**
34 * Info structure for the pseudo random function
35 *
36 * Key should be set at the start to a test-unique value.
37 * Do not forget endianness!
38 * State( v0, v1 ) should be set to zero.
39 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010040typedef struct {
Ronald Cron2058d562020-06-09 17:11:47 +020041 uint32_t key[16];
42 uint32_t v0, v1;
Ronald Cron351f0ee2020-06-10 12:12:18 +020043} mbedtls_test_rnd_pseudo_info;
Ronald Cron2058d562020-06-09 17:11:47 +020044
45/**
46 * This function just returns data from rand().
47 * Although predictable and often similar on multiple
48 * runs, this does not result in identical random on
49 * each run. So do not use this if the results of a
50 * test depend on the random data that is generated.
51 *
52 * rng_state shall be NULL.
53 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010054int mbedtls_test_rnd_std_rand(void *rng_state,
55 unsigned char *output,
56 size_t len);
Ronald Cron2058d562020-06-09 17:11:47 +020057
58/**
Gilles Peskineebf3a4b2021-03-24 00:14:53 +010059 * This function only returns zeros.
Ronald Cron2058d562020-06-09 17:11:47 +020060 *
Gilles Peskineebf3a4b2021-03-24 00:14:53 +010061 * \p rng_state shall be \c NULL.
Ronald Cron2058d562020-06-09 17:11:47 +020062 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010063int mbedtls_test_rnd_zero_rand(void *rng_state,
64 unsigned char *output,
65 size_t len);
Ronald Cron2058d562020-06-09 17:11:47 +020066
67/**
Gilles Peskineebf3a4b2021-03-24 00:14:53 +010068 * This function returns random data based on a buffer it receives.
Ronald Cron2058d562020-06-09 17:11:47 +020069 *
Gilles Peskineebf3a4b2021-03-24 00:14:53 +010070 * \p rng_state shall be a pointer to a #mbedtls_test_rnd_buf_info structure.
Ronald Cron2058d562020-06-09 17:11:47 +020071 *
72 * The number of bytes released from the buffer on each call to
Gilles Peskineb72b7e62021-06-02 21:17:36 +020073 * the random function is specified by \p len.
Ronald Cron2058d562020-06-09 17:11:47 +020074 *
Gilles Peskinebef30192021-03-24 00:48:57 +010075 * After the buffer is empty, this function will call the fallback RNG in the
76 * #mbedtls_test_rnd_buf_info structure if there is one, and
77 * will return #MBEDTLS_ERR_ENTROPY_SOURCE_FAILED otherwise.
Ronald Cron2058d562020-06-09 17:11:47 +020078 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010079int mbedtls_test_rnd_buffer_rand(void *rng_state,
80 unsigned char *output,
81 size_t len);
Ronald Cron2058d562020-06-09 17:11:47 +020082
83/**
84 * This function returns random based on a pseudo random function.
85 * This means the results should be identical on all systems.
86 * Pseudo random is based on the XTEA encryption algorithm to
87 * generate pseudorandom.
88 *
Gilles Peskineebf3a4b2021-03-24 00:14:53 +010089 * \p rng_state shall be a pointer to a #mbedtls_test_rnd_pseudo_info structure.
Ronald Cron2058d562020-06-09 17:11:47 +020090 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010091int mbedtls_test_rnd_pseudo_rand(void *rng_state,
92 unsigned char *output,
93 size_t len);
Ronald Cron2058d562020-06-09 17:11:47 +020094
Ronald Cronb7eb67f2020-06-09 16:57:42 +020095#endif /* TEST_RANDOM_H */