xref: /freebsd/contrib/unbound/util/random.h (revision 38f0b757fd84d17d0fc24739a7cda160c4516d81)
1 /*
2  * util/random.h - thread safe random generator, which is reasonably secure.
3  *
4  * Copyright (c) 2007, NLnet Labs. All rights reserved.
5  *
6  * This software is open source.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * Redistributions of source code must retain the above copyright notice,
13  * this list of conditions and the following disclaimer.
14  *
15  * Redistributions in binary form must reproduce the above copyright notice,
16  * this list of conditions and the following disclaimer in the documentation
17  * and/or other materials provided with the distribution.
18  *
19  * Neither the name of the NLNET LABS nor the names of its contributors may
20  * be used to endorse or promote products derived from this software without
21  * specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
25  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
26  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
27  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33  * POSSIBILITY OF SUCH DAMAGE.
34  */
35 
36 #ifndef UTIL_RANDOM_H
37 #define UTIL_RANDOM_H
38 
39 /**
40  * \file
41  * Thread safe random functions. Similar to arc4random() with an explicit
42  * initialisation routine.
43  */
44 
45 /**
46  * random state structure.
47  */
48 struct ub_randstate;
49 
50 /**
51  * Initialize the system randomness.  Obtains entropy from the system
52  * before a chroot or privilege makes it unavailable.
53  * You do not have to call this, otherwise ub_initstate does so.
54  * @param seed: seed value to create state (if no good entropy is found).
55  */
56 void ub_systemseed(unsigned int seed);
57 
58 /**
59  * Initialize a random generator state for use
60  * @param seed: seed value to create state contents.
61  *	(ignored for arc4random).
62  * @param from: if not NULL, the seed is taken from this random structure.
63  * 	can be used to seed random states via a parent-random-state that
64  * 	is itself seeded with entropy.
65  * @return new state or NULL alloc failure.
66  */
67 struct ub_randstate* ub_initstate(unsigned int seed,
68 	struct ub_randstate* from);
69 
70 /**
71  * Generate next random number from the state passed along.
72  * Thread safe, so random numbers are repeatable.
73  * @param state: must have been initialised with ub_initstate.
74  * @return: random 31 bit value.
75  */
76 long int ub_random(struct ub_randstate* state);
77 
78 /**
79  * Generate random number between 0 and x-1.  No modulo bias.
80  * @param state: must have been initialised with ub_initstate.
81  * @param x: an upper limit. not (negative or zero). must be smaller than 2**31.
82  * @return: random value between 0..x-1. Possibly more than one
83  * random number is picked from the random stream to satisfy this.
84  */
85 long int ub_random_max(struct ub_randstate* state, long int x);
86 
87 /**
88  * Delete the random state.
89  * @param state: to delete.
90  */
91 void ub_randfree(struct ub_randstate* state);
92 
93 #endif /* UTIL_RANDOM_H */
94