=pod

=head1 NAME

Yarrow_Init, Yarrow_Poll, Yarrow_Input, Yarrow_Status, Yarrow_Output, Yarrow_New_Source, Yarrow_Register_Source_Estimator, Yarrow Final - cryptographic pseudo-random number generator

=head1 SYNOPSIS

int Yarrow_Init(Yarrow_CTX *y, const char *filename);

int Yarrow_New_Source(Yarrow_CTX* y, unsigned* source_id);

int Yarrow_Poll(Yarrow_CTX *y, unsigned source_id)

int Yarrow_Input( Yarrow_CTX* y, unsigned source_id,
       const void* sample, size_t size,
       size_t entropy_bits);

int Yarrow_Status(Yarrow_CTX* y, int *num_sources,
       unsigned *source_id, size_t *entropy_bits,
       size_t *entropy_max);

int Yarrow_Output(Yarrow_CTX* y, void* out, size_t size);

int Yarrow_Register_Source_Estimator(Yarrow_CTX* y,
       unsigned source_id,
       size_t (*estimator)(const void* sample,
                           size_t size));

int Yarrow_Final(Yarrow_CTX* y);

=head1 DESCRIPTION

Yarrow_Init() initializes a B<Yarrow_CTX> structure. B<filename> can
be NULL, or the path to a seed file that Yarrow will use to store the
PRNG state for use in later sessions.  Returns B<YARROW_OK> if the
PRNG is seeded on exit, or B<YARROW_NOT_SEEDED> if the PRNG is not yet
seeded.

Yarrow_New_Source() associates entropy sources such as keyboard input,
mouse movements and other unpredictable events with a
B<Yarrow_CTX>. The function assigns a unique number to the new source,
and places it in B<source_id>.

Yarrow_Poll() gathers entropy from the state of the machine and adds
it to the source B<source_id>.  The source has to be allocated by the
user with Yarrow_New_Source.  Returns B<YARROW_OK> if the PRNG is
seeded on exit, or B<YARROW_NOT_SEEDED> if the PRNG is not yet seeded.

Yarrow_Input() is used to add randomness from the source B<source_id>
to the PRNG. It reads B<size> bytes at the address B<sample>. An
estimate of the entropy in bits contained in the sample must be
specified as B<entropy_bits>.

Yarrow_Status() returns B<YARROW_OK> if the PRNG has enough entropy to
produce output, and B<YARROW_NOT_SEEDED> if calls to Yarrow_Output()
would fail.

If num_sources is not NULL, the number of entropy sources that still
need to be seeded is returned in B<*num_sources>.

If source_id is not NULL, the entropy source that is closest to its
threshold is returned in B<*source_id>.  B<*source_id> is set to -1 if
no sources have either reached their threshold or not collected any
entropy yet.

If not NULL, B<*entropy_bits> is set to the current number of bits for
the source B<*source_id>, and B<*entropy_max> to the threshold.

Yarrow_Output() generates B<size> bytes of cryptographically strong
pseudo-random output and places them at B<out>. The return value must
always be checked. If an error occurs, the PRNG may produce
predictable data or no output at all.

Yarrow_Register_Source_Estimator() registers an entropy estimator
for B<source_id>. An entropy estimator is a function that tries to
estimate the entropy in a sample and returns the entropy in bits
in order to detect abnormal situations in which the samples have a very
low entropy.

Yarrow_Final() writes the PRNG state to the seed file and erases it
from memory.

=head1 RETURN VALUES

All functions return B<YARROW_OK> on success. Error conditions are reported
as follows:

 YARROW_FAIL              generic failure
 YARROW_NOT_INIT          YarrowInit() hasn't been called
 YARROW_ALREADY_INIT      YarrowInit() has already been called
 YARROW_NO_DRIVER         driver doesn't exist
 YARROW_CANT_OPEN         can't open driver
 YARROW_BAD_SOURCE        invalid source id
 YARROW_TOO_MANY_SOURCES  can't create any more source IDs
 YARROW_BAD_ARG           invalid argument
 YARROW_ACCESS            insufficient privileges
 YARROW_NOMEM             out of memory
 YARROW_NORSRC            a resource (apart from memory) is exhausted
 YARROW_NOT_SEEDED        not enough entropy to generate output
 YARROW_LOCKING           locking error
 YARROW_NO_STATE          there is no state to load 
 YARROW_STATE_ERROR       error with state load or save
 YARROW_NOT_IMPL          not implemented

=head1 AUTHORS

Yarrow was designed by John Kelsey, Bruce Schneier and Niels Ferguson
of Counterpane Systems. This implementation is (C) 2000 by
Zero-Knowledge Systems Inc.

=cut