random.h File Reference

Implements a random state pool which will let the caller return a series of possibly non-reproducible random values. More...

#include <isc/lang.h>
#include <isc/types.h>
#include <isc/entropy.h>
#include <isc/mem.h>
#include <isc/mutex.h>

Go to the source code of this file.

Defines
#define	ISC_RANDOM_H   1
Typedefs
typedef typedefISC_LANG_BEGINDECLS struct isc_rng	isc_rng_t
	Opaque type.
Functions
void	isc_random_seed (isc_uint32_t seed)
	Set the initial seed of the random state.
void	isc_random_get (isc_uint32_t *val)
	Get a random value.
isc_uint32_t	isc_random_jitter (isc_uint32_t max, isc_uint32_t jitter)
	Get a random value between (max - jitter) and (max). This is useful for jittering timer values.
isc_result_t	isc_rng_create (isc_mem_t *mctx, isc_entropy_t *entropy, isc_rng_t **rngp)
	Creates and initializes a pseudo random number generator. The returned RNG can be used to generate pseudo random numbers.
void	isc_rng_attach (isc_rng_t *source, isc_rng_t **targetp)
	Increments a reference count on the passed RNG.
void	isc_rng_detach (isc_rng_t **rngp)
	Decrements a reference count on the passed RNG. If the reference count reaches 0, the RNG is destroyed.
isc_uint16_t	isc_rng_random (isc_rng_t *rngctx)
	Returns a pseudo random 16-bit unsigned integer.
isc_uint16_t	isc_rng_uniformrandom (isc_rng_t *rngctx, isc_uint16_t upper_bound)
	Returns a uniformly distributed pseudo random 16-bit unsigned integer.

---

Detailed Description

Implements a random state pool which will let the caller return a series of possibly non-reproducible random values.

Note that the strength of these numbers is not all that high, and should not be used in cryptography functions. It is useful for jittering values a bit here and there, such as timeouts, etc.

Definition in file random.h.

---

Define Documentation

#define ISC_RANDOM_H   1

Definition at line 21 of file random.h.

---

Typedef Documentation

typedef typedefISC_LANG_BEGINDECLS struct isc_rng isc_rng_t

Opaque type.

Definition at line 41 of file random.h.

---

Function Documentation

void isc_random_seed

(

isc_uint32_t

seed

)

Set the initial seed of the random state.

Definition at line 108 of file random.c.

References initialize().

void isc_random_get

(

isc_uint32_t *

val

)

Get a random value.

Requires: val != NULL.

Definition at line 126 of file random.c.

References initialize(), and REQUIRE.

Referenced by ATF_TC_BODY(), chacha_stir(), control_recvmessage(), dns_acache_createentry(), entry_stale(), expirenode(), fctx_cancelquery(), followup_lookup(), generate_salt(), get_dispsocket(), insert_nodes(), isc_file_openuniquemode(), isc_file_renameunique(), isc_hash_ctxinit(), isc_pool_get(), isc_random_jitter(), isc_rng_create(), isc_taskpool_gettask(), main(), new_adbentry(), ns_client_addopt(), remove_nodes(), set_resigntime(), setup_lookup(), towiresorted(), xfrin_create(), zone_nsec3chain(), zone_resigninc(), and zone_sign().

isc_uint32_t isc_random_jitter	(	isc_uint32_t	max,
		isc_uint32_t	jitter
	)

Get a random value between (max - jitter) and (max). This is useful for jittering timer values.

Definition at line 151 of file random.c.

References isc_random_get(), and REQUIRE.

Referenced by dns_zone_refresh(), signwithkey(), and zone_postload().

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

Creates and initializes a pseudo random number generator. The returned RNG can be used to generate pseudo random numbers.

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

Requires:

• mctx is a pointer to a valid memory context.
• entropy is an optional entopy source (can be NULL)
• rngp != NULL && *rngp == NULL is where a pointer to the RNG is returned.

Ensures:

• If result is ISC_R_SUCCESS: *rngp points to a valid RNG.

• If result is failure: *rngp does not point to a valid RNG.

Returns:

• ISC_R_SUCCESS Success
• ISC_R_NOMEMORY Resource limit: Out of Memory

Definition at line 175 of file random.c.

References CHACHA_BUFFERSIZE, chacha_reinit(), isc_entropy_getdata(), isc_mem_attach(), isc_mem_get, isc_mem_put, isc_mutex_init, ISC_R_NOMEMORY, ISC_R_SUCCESS, isc_random_get(), isc_entropy::magic, REQUIRE, RNG_MAGIC, and RUNTIME_CHECK.

Referenced by dns_dispatchmgr_create(), and random_test().

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

Increments a reference count on the passed RNG.

Requires:

• source the RNG struct to attach to (is refcount is incremented)
• targetp != NULL && *targetp == NULL where a pointer to the reference incremented RNG is returned.

Definition at line 231 of file random.c.

References LOCK, REQUIRE, UNLOCK, and VALID_RNG.

Referenced by dispatch_allocate().

void isc_rng_detach

(

isc_rng_t **

rngp

)

Decrements a reference count on the passed RNG. If the reference count reaches 0, the RNG is destroyed.

Requires:

• rngp != NULL the RNG struct to decrement reference for

Definition at line 254 of file random.c.

References destroy(), INSIST, ISC_FALSE, ISC_TRUE, LOCK, REQUIRE, UNLOCK, and VALID_RNG.

Referenced by destroy_mgr(), dispatch_allocate(), dispatch_free(), and random_test().

isc_uint16_t isc_rng_random

(

isc_rng_t *

rngctx

)

Returns a pseudo random 16-bit unsigned integer.

Definition at line 368 of file random.c.

References chacha_getuint16(), chacha_stir(), LOCK, REQUIRE, UNLOCK, and VALID_RNG.

Referenced by dns_dispatch_addresponse3(), isc_rng_uniformrandom(), and random_test().

isc_uint16_t isc_rng_uniformrandom	(	isc_rng_t *	rngctx,
		isc_uint16_t	upper_bound
	)

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

Definition at line 386 of file random.c.

References isc_rng_random(), r, REQUIRE, and VALID_RNG.

Referenced by get_dispsocket(), and get_udpsocket().

---