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