Random Functions

Overview

// 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;

// structs

struct apr_crypto_hash_t;

// global 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 Documentation

Typedefs

typedef struct apr_random_t apr_random_t

Opaque PRNG structure.

Global Functions

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_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

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_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

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_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_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

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_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_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

void
apr_random_after_fork(apr_proc_t* proc)

Mix the randomness pools after forking. 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.

Parameters:

proc	The resulting process handle from apr_proc_fork()