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

   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