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
Prototype Functions
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:
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:
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
Contact: Richard Gooch
Web Development: Ariel Internet Services