Random Functions

Data Structures
struct	apr_crypto_hash_t

Typedefs
typedef struct apr_crypto_hash_t	apr_crypto_hash_t
typedef void	apr_crypto_hash_init_t(apr_crypto_hash_t *hash)
typedef void	apr_crypto_hash_add_t(apr_crypto_hash_t *hash, const void *data, apr_size_t bytes)
typedef void	apr_crypto_hash_finish_t(apr_crypto_hash_t *hash, unsigned char *result)
typedef struct apr_random_t	apr_random_t

Functions
apr_status_t	apr_generate_random_bytes (unsigned char *buf, apr_size_t length)
apr_crypto_hash_t *	apr_crypto_sha256_new (apr_pool_t *p)
void	apr_random_init (apr_random_t *g, apr_pool_t *p, apr_crypto_hash_t *pool_hash, apr_crypto_hash_t *key_hash, apr_crypto_hash_t *prng_hash)
apr_random_t *	apr_random_standard_new (apr_pool_t *p)
void	apr_random_add_entropy (apr_random_t *g, const void *entropy_, apr_size_t bytes)
apr_status_t	apr_random_insecure_bytes (apr_random_t *g, void *random, apr_size_t bytes)
apr_status_t	apr_random_secure_bytes (apr_random_t *g, void *random, apr_size_t bytes)
void	apr_random_barrier (apr_random_t *g)
apr_status_t	apr_random_secure_ready (apr_random_t *r)
apr_status_t	apr_random_insecure_ready (apr_random_t *r)
void	apr_random_after_fork (apr_proc_t *proc)

Detailed Description

Typedef Documentation

apr_random_t

typedef struct apr_random_t apr_random_t

Opaque PRNG structure.

Function Documentation

apr_crypto_sha256_new()

apr_crypto_hash_t* apr_crypto_sha256_new

(

apr_pool_t *

p

)

Allocate and initialize the SHA-256 context

Parameters

p	The pool to allocate from

apr_generate_random_bytes()

apr_status_t apr_generate_random_bytes	(	unsigned char *	buf,
		apr_size_t	length
	)

Generate random bytes.

Parameters

buf	Buffer to fill with random bytes
length	Length of buffer in bytes

apr_random_add_entropy()

void apr_random_add_entropy	(	apr_random_t *	g,
		const void *	entropy_,
		apr_size_t	bytes
	)

Mix the randomness pools.

Parameters

g	The PRNG state
entropy_	Entropy buffer
bytes	Length of entropy_ in bytes

apr_random_after_fork()

void apr_random_after_fork

(

apr_proc_t *

proc

)

Mix the randomness pools after forking.

Parameters

proc	The resulting process handle from apr_proc_fork()

Remarks

Call this in the child after forking to mix the randomness pools. Note that its generally a bad idea to fork a process with a real PRNG in it - better to have the PRNG externally and get the randomness from there. However, if you really must do it, then you should supply all your entropy to all the PRNGs - don't worry, they won't produce the same output.

Note that apr_proc_fork() calls this for you, so only weird applications need ever call it themselves.

apr_random_barrier()

void apr_random_barrier

(

apr_random_t *

g

)

Ensures that E bits of conditional entropy are mixed into the PRNG before any further randomness is extracted.

Parameters

g	The RNG state

apr_random_init()

void apr_random_init	(	apr_random_t *	g,
		apr_pool_t *	p,
		apr_crypto_hash_t *	pool_hash,
		apr_crypto_hash_t *	key_hash,
		apr_crypto_hash_t *	prng_hash
	)

Initialize a PRNG state

Parameters

g	The PRNG state
p	The pool to allocate from
pool_hash	Pool hash functions
key_hash	Key hash functions
prng_hash	PRNG hash functions

apr_random_insecure_bytes()

apr_status_t apr_random_insecure_bytes	(	apr_random_t *	g,
		void *	random,
		apr_size_t	bytes
	)

Generate cryptographically insecure random bytes.

Parameters

g	The RNG state
random	Buffer to fill with random bytes
bytes	Length of buffer in bytes

apr_random_insecure_ready()

apr_status_t apr_random_insecure_ready

(

apr_random_t *

r

)

Return APR_SUCCESS if the PRNG has been seeded with enough data, APR_ENOTENOUGHENTROPY otherwise.

Parameters

r	The PRNG state

apr_random_secure_bytes()

apr_status_t apr_random_secure_bytes	(	apr_random_t *	g,
		void *	random,
		apr_size_t	bytes
	)

Generate cryptographically secure random bytes.

Parameters

g	The RNG state
random	Buffer to fill with random bytes
bytes	Length of buffer in bytes

apr_random_secure_ready()

apr_status_t apr_random_secure_ready

(

apr_random_t *

r

)

Return APR_SUCCESS if the cryptographic PRNG has been seeded with enough data, APR_ENOTENOUGHENTROPY otherwise.

Parameters

r	The RNG state

apr_random_standard_new()

apr_random_t* apr_random_standard_new

(

apr_pool_t *

p

)

Allocate and initialize (apr_crypto_sha256_new) a new PRNG state.

Parameters

p	The pool to allocate from