1238106Sdes/* 2238106Sdes * util/random.h - thread safe random generator, which is reasonably secure. 3238106Sdes * 4238106Sdes * Copyright (c) 2007, NLnet Labs. All rights reserved. 5238106Sdes * 6238106Sdes * This software is open source. 7238106Sdes * 8238106Sdes * Redistribution and use in source and binary forms, with or without 9238106Sdes * modification, are permitted provided that the following conditions 10238106Sdes * are met: 11238106Sdes * 12238106Sdes * Redistributions of source code must retain the above copyright notice, 13238106Sdes * this list of conditions and the following disclaimer. 14238106Sdes * 15238106Sdes * Redistributions in binary form must reproduce the above copyright notice, 16238106Sdes * this list of conditions and the following disclaimer in the documentation 17238106Sdes * and/or other materials provided with the distribution. 18238106Sdes * 19238106Sdes * Neither the name of the NLNET LABS nor the names of its contributors may 20238106Sdes * be used to endorse or promote products derived from this software without 21238106Sdes * specific prior written permission. 22238106Sdes * 23238106Sdes * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 24269257Sdes * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 25269257Sdes * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 26269257Sdes * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 27269257Sdes * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 28269257Sdes * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 29269257Sdes * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 30269257Sdes * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 31269257Sdes * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 32269257Sdes * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 33269257Sdes * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 34238106Sdes */ 35238106Sdes 36238106Sdes#ifndef UTIL_RANDOM_H 37238106Sdes#define UTIL_RANDOM_H 38238106Sdes 39238106Sdes/** 40238106Sdes * \file 41238106Sdes * Thread safe random functions. Similar to arc4random() with an explicit 42238106Sdes * initialisation routine. 43238106Sdes */ 44238106Sdes 45238106Sdes/** 46238106Sdes * random state structure. 47238106Sdes */ 48238106Sdesstruct ub_randstate; 49238106Sdes 50238106Sdes/** 51238106Sdes * Initialize the system randomness. Obtains entropy from the system 52238106Sdes * before a chroot or privilege makes it unavailable. 53238106Sdes * You do not have to call this, otherwise ub_initstate does so. 54238106Sdes * @param seed: seed value to create state (if no good entropy is found). 55238106Sdes */ 56238106Sdesvoid ub_systemseed(unsigned int seed); 57238106Sdes 58238106Sdes/** 59238106Sdes * Initialize a random generator state for use 60238106Sdes * @param seed: seed value to create state contents. 61238106Sdes * (ignored for arc4random). 62238106Sdes * @param from: if not NULL, the seed is taken from this random structure. 63238106Sdes * can be used to seed random states via a parent-random-state that 64238106Sdes * is itself seeded with entropy. 65238106Sdes * @return new state or NULL alloc failure. 66238106Sdes */ 67238106Sdesstruct ub_randstate* ub_initstate(unsigned int seed, 68238106Sdes struct ub_randstate* from); 69238106Sdes 70238106Sdes/** 71238106Sdes * Generate next random number from the state passed along. 72238106Sdes * Thread safe, so random numbers are repeatable. 73238106Sdes * @param state: must have been initialised with ub_initstate. 74238106Sdes * @return: random 31 bit value. 75238106Sdes */ 76238106Sdeslong int ub_random(struct ub_randstate* state); 77238106Sdes 78238106Sdes/** 79238106Sdes * Generate random number between 0 and x-1. No modulo bias. 80238106Sdes * @param state: must have been initialised with ub_initstate. 81238106Sdes * @param x: an upper limit. not (negative or zero). must be smaller than 2**31. 82238106Sdes * @return: random value between 0..x-1. Possibly more than one 83238106Sdes * random number is picked from the random stream to satisfy this. 84238106Sdes */ 85238106Sdeslong int ub_random_max(struct ub_randstate* state, long int x); 86238106Sdes 87238106Sdes/** 88238106Sdes * Delete the random state. 89238106Sdes * @param state: to delete. 90238106Sdes */ 91238106Sdesvoid ub_randfree(struct ub_randstate* state); 92238106Sdes 93238106Sdes#endif /* UTIL_RANDOM_H */ 94