/*

[0] Fix | Delete

* Copyright (C) Internet Systems Consortium, Inc. ("ISC")

[1] Fix | Delete

*

[2] Fix | Delete

* This Source Code Form is subject to the terms of the Mozilla Public

[3] Fix | Delete

* License, v. 2.0. If a copy of the MPL was not distributed with this

[4] Fix | Delete

* file, you can obtain one at https://mozilla.org/MPL/2.0/.

[5] Fix | Delete

*

[6] Fix | Delete

* See the COPYRIGHT file distributed with this work for additional

[7] Fix | Delete

* information regarding copyright ownership.

[8] Fix | Delete

*/

[9] Fix | Delete

[10] Fix | Delete

#ifndef ISC_RANDOM_H

[11] Fix | Delete

#define ISC_RANDOM_H 1

[12] Fix | Delete

[13] Fix | Delete

#include <isc/lang.h>

[14] Fix | Delete

#include <isc/types.h>

[15] Fix | Delete

#include <isc/entropy.h>

[16] Fix | Delete

#include <isc/mem.h>

[17] Fix | Delete

#include <isc/mutex.h>

[18] Fix | Delete

[19] Fix | Delete

/*! \file isc/random.h

[20] Fix | Delete

* \brief Implements pseudo random number generators.

[21] Fix | Delete

*

[22] Fix | Delete

* Two pseudo-random number generators are implemented, in isc_random_*

[23] Fix | Delete

* and isc_rng_*. Neither one is very strong; they should not be used

[24] Fix | Delete

* in cryptography functions.

[25] Fix | Delete

*

[26] Fix | Delete

* isc_random_* is based on arc4random if it is available on the system.

[27] Fix | Delete

* Otherwise it is based on the posix srand() and rand() functions.

[28] Fix | Delete

* It is useful for jittering values a bit here and there, such as

[29] Fix | Delete

* timeouts, etc, but should not be relied upon to generate

[30] Fix | Delete

* unpredictable sequences (for example, when choosing transaction IDs).

[31] Fix | Delete

*

[32] Fix | Delete

* isc_rng_* is based on ChaCha20, and is seeded and stirred from the

[33] Fix | Delete

* system entropy source. It is stronger than isc_random_* and can

[34] Fix | Delete

* be used for generating unpredictable sequences. It is still not as

[35] Fix | Delete

* good as using system entropy directly (see entropy.h) and should not

[36] Fix | Delete

* be used for cryptographic functions such as key generation.

[37] Fix | Delete

*/

[38] Fix | Delete

[39] Fix | Delete

ISC_LANG_BEGINDECLS

[40] Fix | Delete

[41] Fix | Delete

typedef struct isc_rng isc_rng_t;

[42] Fix | Delete

/*%<

[43] Fix | Delete

* Opaque type

[44] Fix | Delete

*/

[45] Fix | Delete

[46] Fix | Delete

void

[47] Fix | Delete

isc_random_seed(uint32_t seed);

[48] Fix | Delete

/*%<

[49] Fix | Delete

* Set the initial seed of the random state.

[50] Fix | Delete

*/

[51] Fix | Delete

[52] Fix | Delete

void

[53] Fix | Delete

isc_random_get(uint32_t *val);

[54] Fix | Delete

/*%<

[55] Fix | Delete

* Get a random value.

[56] Fix | Delete

*

[57] Fix | Delete

* Requires:

[58] Fix | Delete

* val != NULL.

[59] Fix | Delete

*/

[60] Fix | Delete

[61] Fix | Delete

uint32_t

[62] Fix | Delete

isc_random_jitter(uint32_t max, uint32_t jitter);

[63] Fix | Delete

/*%<

[64] Fix | Delete

* Get a random value between (max - jitter) and (max).

[65] Fix | Delete

* This is useful for jittering timer values.

[66] Fix | Delete

*/

[67] Fix | Delete

[68] Fix | Delete

isc_result_t

[69] Fix | Delete

isc_rng_create(isc_mem_t *mctx, isc_entropy_t *entropy, isc_rng_t **rngp);

[70] Fix | Delete

/*%<

[71] Fix | Delete

* Creates and initializes a pseudo random number generator. The

[72] Fix | Delete

* returned RNG can be used to generate pseudo random numbers.

[73] Fix | Delete

*

[74] Fix | Delete

* The reference count of the returned RNG is set to 1.

[75] Fix | Delete

*

[76] Fix | Delete

* Requires:

[77] Fix | Delete

* \li mctx is a pointer to a valid memory context.

[78] Fix | Delete

* \li entropy is an optional entopy source (can be NULL)

[79] Fix | Delete

* \li rngp != NULL && *rngp == NULL is where a pointer to the RNG is

[80] Fix | Delete

* returned.

[81] Fix | Delete

*

[82] Fix | Delete

* Ensures:

[83] Fix | Delete

*\li If result is ISC_R_SUCCESS:

[84] Fix | Delete

* *rngp points to a valid RNG.

[85] Fix | Delete

*

[86] Fix | Delete

*\li If result is failure:

[87] Fix | Delete

* *rngp does not point to a valid RNG.

[88] Fix | Delete

*

[89] Fix | Delete

* Returns:

[90] Fix | Delete

*\li #ISC_R_SUCCESS Success

[91] Fix | Delete

*\li #ISC_R_NOMEMORY Resource limit: Out of Memory

[92] Fix | Delete

*/

[93] Fix | Delete

[94] Fix | Delete

void

[95] Fix | Delete

isc_rng_attach(isc_rng_t *source, isc_rng_t **targetp);

[96] Fix | Delete

/*%<

[97] Fix | Delete

* Increments a reference count on the passed RNG.

[98] Fix | Delete

*

[99] Fix | Delete

* Requires:

[100] Fix | Delete

* \li source the RNG struct to attach to (is refcount is incremented)

[101] Fix | Delete

* \li targetp != NULL && *targetp == NULL where a pointer to the

[102] Fix | Delete

* reference incremented RNG is returned.

[103] Fix | Delete

*/

[104] Fix | Delete

[105] Fix | Delete

void

[106] Fix | Delete

isc_rng_detach(isc_rng_t **rngp);

[107] Fix | Delete

/*%<

[108] Fix | Delete

* Decrements a reference count on the passed RNG. If the reference

[109] Fix | Delete

* count reaches 0, the RNG is destroyed.

[110] Fix | Delete

*

[111] Fix | Delete

* Requires:

[112] Fix | Delete

* \li rngp != NULL the RNG struct to decrement reference for

[113] Fix | Delete

*/

[114] Fix | Delete

[115] Fix | Delete

uint16_t

[116] Fix | Delete

isc_rng_random(isc_rng_t *rngctx);

[117] Fix | Delete

/*%<

[118] Fix | Delete

* Returns a pseudo random 16-bit unsigned integer.

[119] Fix | Delete

*/

[120] Fix | Delete

[121] Fix | Delete

uint16_t

[122] Fix | Delete

isc_rng_uniformrandom(isc_rng_t *rngctx, uint16_t upper_bound);

[123] Fix | Delete

/*%<

[124] Fix | Delete

* Returns a uniformly distributed pseudo-random 16-bit unsigned integer

[125] Fix | Delete

* less than 'upper_bound'.

[126] Fix | Delete

*/

[127] Fix | Delete

[128] Fix | Delete

ISC_LANG_ENDDECLS

[129] Fix | Delete

[130] Fix | Delete

#endif /* ISC_RANDOM_H */

[131] Fix | Delete

[132] Fix | Delete