bsd/dev/random/YarrowCoreLib/src/readme-prnguser.txt

12345678901234567890123456789012345678901234567890123456789012345678901234567890

Description of User Routines in Prngcore
----------------------------------------------

This files describes routines in prngcore that are designed to be called by the
user (ie client apps). Those interested in the details of the library are
directed to readme-prngcoder.

Files of interest in this directory
-----------------------------------

yarrow.h

Main header file (and the only one needed) for client apps.

userdefines.h

Header file with macros that can be defined to specify the system that this
code is being compiled on, as well as other details of the prng operation.

usersources.h

Header file containing the names of the various user sources of entropic data.
You can add/delete/rename sources by altering the entries in the enumeration.


PRNG Client Routines
--------------------

All major routines return the success/error value for their operation.

prngOutput(outbuf,outbuflen)

Writes outbuflen worth of "random" data to outbuf. This routine has
backtracking protection, but you should call prngAllowReseed whenever you can
spare the cycles to guarantee good output.

prngStretch(inbuf,inbuflen,outbuf,outbuflen)

Takes inbuflen bytes of data from inbuf and turns it into outbuflen bytes of
data stored in outbuf.

prngInput(inbuf,inbuflen,poolnum,estbits)

Takes inbuflen bytes of data from inbuf and places it in entropy pool poolnum.
The user entropy pool names can be found in usersources.h (see above).

prngForceReseed(ticks)

Forces a reseed that lasts about ticks ticks long. Be very careful when using
this function to ensure that you do not produce a poor output state.  It is
suggested that you instead use prngAllowReseed.

prngAllowReseed(ticks)

Will force a reseed if there is enough entropy. A reseed (of length ticks)
will be done if the total entropy estimate, ignoring the K greatest sources,
is greater than THRESHOLD. Currently, K = 0 (a bad idea) and THRESHOLD = 100
(likely to remain so). These values can be found and edited in userdefines.h.
Will return PRNG_ERR_NOT_ENOUGH_ENTROPY if there is not enough entropy in the
pool at this time.

prngProcessSeedBuffer(buf,ticks)

Takes 20 bytes of data from buf and churns it into the entropy pool, and then
forces a reseed of length ticks. The first 20 bytes of output are then
returned in buf for future use with this function.  It is recommended that data
used with this function be stored very securely.

prngSlowPoll(pollsize)

Does a slow poll to collect a large amount of vaguely random data from the OS
itself.  The poll with collect at most pollsize bytes, and this parameter can
be used to control (approximately) the length of the poll. The collected data
is fed into the entropy pool.  After calling this function you may call either
allow (recommended) or force a reseed if desired.

--------

Any questions can be directed to the programmer (me), Ari Benbasat, at
pigsfly@unixg.ubc.ca.  Comments would be greatly appreciated.  Please cc: all
e-mail to Bruce Schneier, John Kelsey and Chris Hall
{schneier,kelsey,hall}@counterpane.com.

Thank you.


i
Commit	Line	Data
	1	12345678901234567890123456789012345678901234567890123456789012345678901234567890
	2
	3	Description of User Routines in Prngcore
	4	----------------------------------------------
	5
	6	This files describes routines in prngcore that are designed to be called by the
	7	user (ie client apps). Those interested in the details of the library are
	8	directed to readme-prngcoder.
	9
	10	Files of interest in this directory
	11	-----------------------------------
	12
	13	yarrow.h
	14
	15	Main header file (and the only one needed) for client apps.
	16
	17	userdefines.h
	18
	19	Header file with macros that can be defined to specify the system that this
	20	code is being compiled on, as well as other details of the prng operation.
	21
	22	usersources.h
	23
	24	Header file containing the names of the various user sources of entropic data.
	25	You can add/delete/rename sources by altering the entries in the enumeration.
	26
	27
	28	PRNG Client Routines
	29	--------------------
	30
	31	All major routines return the success/error value for their operation.
	32
	33	prngOutput(outbuf,outbuflen)
	34
	35	Writes outbuflen worth of "random" data to outbuf. This routine has
	36	backtracking protection, but you should call prngAllowReseed whenever you can
	37	spare the cycles to guarantee good output.
	38
	39	prngStretch(inbuf,inbuflen,outbuf,outbuflen)
	40
	41	Takes inbuflen bytes of data from inbuf and turns it into outbuflen bytes of
	42	data stored in outbuf.
	43
	44	prngInput(inbuf,inbuflen,poolnum,estbits)
	45
	46	Takes inbuflen bytes of data from inbuf and places it in entropy pool poolnum.
	47	The user entropy pool names can be found in usersources.h (see above).
	48
	49	prngForceReseed(ticks)
	50
	51	Forces a reseed that lasts about ticks ticks long. Be very careful when using
	52	this function to ensure that you do not produce a poor output state. It is
	53	suggested that you instead use prngAllowReseed.
	54
	55	prngAllowReseed(ticks)
	56
	57	Will force a reseed if there is enough entropy. A reseed (of length ticks)
	58	will be done if the total entropy estimate, ignoring the K greatest sources,
	59	is greater than THRESHOLD. Currently, K = 0 (a bad idea) and THRESHOLD = 100
	60	(likely to remain so). These values can be found and edited in userdefines.h.
	61	Will return PRNG_ERR_NOT_ENOUGH_ENTROPY if there is not enough entropy in the
	62	pool at this time.
	63
	64	prngProcessSeedBuffer(buf,ticks)
	65
	66	Takes 20 bytes of data from buf and churns it into the entropy pool, and then
	67	forces a reseed of length ticks. The first 20 bytes of output are then
	68	returned in buf for future use with this function. It is recommended that data
	69	used with this function be stored very securely.
	70
	71	prngSlowPoll(pollsize)
	72
	73	Does a slow poll to collect a large amount of vaguely random data from the OS
	74	itself. The poll with collect at most pollsize bytes, and this parameter can
	75	be used to control (approximately) the length of the poll. The collected data
	76	is fed into the entropy pool. After calling this function you may call either
	77	allow (recommended) or force a reseed if desired.
	78
	79	--------
	80
	81	Any questions can be directed to the programmer (me), Ari Benbasat, at
	82	pigsfly@unixg.ubc.ca. Comments would be greatly appreciated. Please cc: all
	83	e-mail to Bruce Schneier, John Kelsey and Chris Hall
	84	{schneier,kelsey,hall}@counterpane.com.
	85
	86	Thank you.
	87
	88
	89
	90	i