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