# The "rp" Package

These routines are meant to provide management of cryptographically strong random pools of bytes. Partially random data (entropy) may be added and extracted from a pool. As data is added, the pool is stirred to randomly distribute the bits. Data extracted from a random pool may be used in the generation of unpredictable (secure) session keys for cryptographic algorithms.

Library: karma
Link With: -lkarma

#### Functions

rp_create | Create a pool of random bytes.
rp_add_bytes | Add bytes (entropy) to a random pool.
rp_get_bytes | Get bytes of data from a random pool.
rp_destroy | Destroy a random pool of bytes, erasing all information.
rp_destroy_all | Destroy all randpools.
rp_add_time_noise | Add time-based entropy to a randpool.
rp_register_destroy_func | Register randpool destroy callback.

#### Prototype Functions

rp_PROTO_hash_func | Hash callback.
rp_PROTO_destroy_func | Destroy callback.

## Functions

RandPool rp_create ( unsigned int size, unsigned int hash_digest_size, unsigned int hash_block_size, void (*hash_func) () )

This routine will create a random pool of bytes to which random data may be subsequently added or extracted. The pool is initialised with pseudo-random data (which is *not* cryptographically secure). When data is added to the pool, the pool is stirred using a supplied hash function. Bytes extracted from the pool should be cryptographically secure.

Parameters:

- size : The size of the pool.
- hash_digest_size : The size of the hash buffer.
- hash_block_size : The size of the hash block.
- hash_func : The hash function. The prototype function is rp_PROTO_hash_func.

Returns: A RandPool object on success, else NULL.
Multithreading Level: Unsafe

void rp_add_bytes (RandPool rp, CONST unsigned char *buf, unsigned int length)

This routine will add bytes of data (entropy) into a pool. The pool is then stirred using its registered hash function in order to distribute the bits.

Parameters:

- rp : The random pool.
- buf : The bytes to add to the pool.
- length : The number of bytes to add to the pool.

Returns: Nothing.
Multithreading Level: Unsafe

void rp_get_bytes (RandPool rp, unsigned char *buf, unsigned int length)

Get bytes of data from a random pool.

Parameters:

- rp : The random pool.
- buf : The bytes to get from the pool will be written here. These bytes should be random and cryptographically secure.
- length : The number of bytes to get from the pool.

Returns: Nothing.
Multithreading Level: Unsafe

void rp_destroy (RandPool rp)

Destroy a random pool of bytes, erasing all information.

Parameters:

- rp : The random pool.

Returns: Nothing.
Multithreading Level: Unsafe

void rp_destroy_all ()

This routine will destroy all randpools. The routine is meant to be called from the exit(3) function. It should also be called by the application prior to execve(2).

Parameters:

This function takes no parameters

Returns: Nothing.
Multithreading Level: Unsafe

void rp_add_time_noise (RandPool rp)

This routine will add bytes of data (entropy) into a pool, derived from the system time. It is suggested that this routine be called by various callback routines to assist in the addition of entropy.

Parameters:

- rp : The random pool.

Returns: Nothing.
Multithreading Level: Unsafe

void rp_register_destroy_func (RandPool rp, void (*destroy_func) (),void *info)

This routine will register a routine which should be called when a random pool is destroyed.

Parameters:

- rp : The random pool.
- destroy_func : The function which is called when the random pool is destroyed. The prototype function is rp_PROTO_destroy_func. Multiple destroy functions may be registered, with the first one registered being the first one called upon destroy.
- info : A pointer to the arbitrary information passed to the destroy function. This may be NULL.

Returns: Nothing.
Multithreading Level: Unsafe

## Prototype Functions

void rp_PROTO_hash_func (unsigned char buffer[hash_digest_size], CONST unsigned char block[hash_block_size];)

This routine is called when a hash buffer must be scrambled with a block of data.

Parameters:

- buffer : The hash buffer.
- block : The block to add to the hash buffer data.

Returns: Nothing.
Multithreading Level: Unsafe

void rp_PROTO_destroy_func (RandPool rp, void *info)

This routine is called when a random pool is destroyed.

Parameters:

- rp : The random pool.
- info : The arbitrary information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

Back to Karma Home Page