1/* (c) Magnus Auvinen. See licence.txt in the root of the distribution for more information. */
2/* If you are missing that file, acquire a complete release at teeworlds.com. */
3
4#ifndef BASE_SECURE_H
5#define BASE_SECURE_H
6
7/**
8 * Secure random number generation.
9 *
10 * @defgroup Secure-Random Secure Random
11 */
12
13/**
14 * Generates a null-terminated password of length `2 * random_length`.
15 *
16 * @ingroup Secure-Random
17 *
18 * @param buffer Pointer to the start of the output buffer.
19 * @param length Length of the buffer.
20 * @param random Pointer to a randomly-initialized array of shorts.
21 * @param random_length Length of the short array.
22 */
23void generate_password(char *buffer, unsigned length, const unsigned short *random, unsigned random_length);
24
25/**
26 * Fills the buffer with the specified amount of random password characters.
27 *
28 * @ingroup Secure-Random
29 *
30 * @param buffer Pointer to the start of the buffer.
31 * @param length Length of the buffer.
32 * @param pw_length Length of the desired password.
33 *
34 * @remark The desired password length must be greater or equal to 6,
35 * even and smaller or equal to 128.
36 */
37void secure_random_password(char *buffer, unsigned length, unsigned pw_length);
38
39/**
40 * Fills the buffer with the specified amount of random bytes.
41 *
42 * @ingroup Secure-Random
43 *
44 * @param bytes Pointer to the start of the buffer.
45 * @param length Length of the buffer.
46 */
47void secure_random_fill(void *bytes, unsigned length);
48
49/**
50 * Returns a random nonnegative integer below the given number,
51 * with a uniform distribution.
52 *
53 * @ingroup Secure-Random
54 *
55 * @param below Upper limit (exclusive) of integers to return.
56 *
57 * @return Random nonnegative below the given number.
58 */
59int secure_rand_below(int below);
60
61#endif
62