freeswan/lib/prng.3

   1 .TH IPSEC_PRNG 3 "1 April 2002"
   2 .\" RCSID $Id: prng.3,v 1.4 2002/04/02 00:46:47 mcr Exp $
   3 .SH NAME
   4 ipsec prng_init \- initialize IPsec pseudorandom-number generator
   5 .br
   6 ipsec prng_bytes \- get bytes from IPsec pseudorandom-number generator
   7 .br
   8 ipsec prng_final \- close down IPsec pseudorandom-number generator
   9 .SH SYNOPSIS
  10 .B "#include <freeswan.h>
  11 .sp
  12 .B "void prng_init(struct prng *prng,"
  13 .ti +1c
  14 .B "const unsigned char *key, size_t keylen);"
  15 .br
  16 .B "void prng_bytes(struct prng *prng, char *dst,"
  17 .ti +1c
  18 .B "size_t dstlen);"
  19 .br
  20 .B "unsigned long prng_count(struct prng *prng);"
  21 .br
  22 .B "void prng_final(struct prng *prng);"
  23 .SH DESCRIPTION
  24 .I Prng_init
  25 initializes a crypto-quality pseudo-random-number generator from a key;
  26 .I prng_bytes
  27 obtains pseudo-random bytes from it;
  28 .I prng_count
  29 reports the number of bytes extracted from it to date;
  30 .I prng_final
  31 closes it down.
  32 It is the user's responsibility to initialize a PRNG before using it,
  33 and not to use it again after it is closed down.
  34 .PP
  35 .I Prng_init
  36 initializes,
  37 or re-initializes,
  38 the specified
  39 .I prng
  40 from the
  41 .IR key ,
  42 whose length is given by
  43 .IR keylen .
  44 The user must allocate the
  45 .B "struct prng"
  46 pointed to by
  47 .IR prng .
  48 There is no particular constraint on the length of the key,
  49 although a key longer than 256 bytes is unnecessary because
  50 only the first 256 would be used.
  51 Initialization requires on the order of 3000 integer operations,
  52 independent of key length.
  53 .PP
  54 .I Prng_bytes
  55 obtains
  56 .I dstlen
  57 pseudo-random bytes from the PRNG and puts them in
  58 .IR buf .
  59 This is quite fast,
  60 on the order of 10 integer operations per byte.
  61 .PP
  62 .I Prng_count
  63 reports the number of bytes obtained from the PRNG
  64 since it was (last) initialized.
  65 .PP
  66 .I Prng_final
  67 closes down a PRNG by
  68 zeroing its internal memory,
  69 obliterating all trace of the state used to generate its previous output.
  70 This requires on the order of 250 integer operations.
  71 .PP
  72 The
  73 .B <freeswan.h>
  74 header file supplies the definition of the
  75 .B prng
  76 structure.
  77 Examination of its innards is discouraged, as they may change.
  78 .PP
  79 The PRNG algorithm
  80 used by these functions is currently identical to that of RC4(TM).
  81 This algorithm is cryptographically strong,
  82 sufficiently unpredictable that even a hostile observer will
  83 have difficulty determining the next byte of output from past history,
  84 provided it is initialized from a reasonably large key composed of
  85 highly random bytes (see
  86 .IR random (4)).
  87 The usual run of software pseudo-random-number generators
  88 (e.g.
  89 .IR random (3))
  90 are
  91 .I not
  92 cryptographically strong.
  93 .PP
  94 The well-known attacks against RC4(TM),
  95 e.g. as found in 802.11b's WEP encryption system,
  96 apply only if multiple PRNGs are initialized with closely-related keys
  97 (e.g., using a counter appended to a base key).
  98 If such keys are used, the first few hundred pseudo-random bytes
  99 from each PRNG should be discarded,
 100 to give the PRNGs a chance to randomize their innards properly.
 101 No useful attacks are known if the key is well randomized to begin with.
 102 .SH SEE ALSO
 103 random(3), random(4)
 104 .br
 105 Bruce Schneier,
 106 \fIApplied Cryptography\fR, 2nd ed., 1996, ISBN 0-471-11709-9,
 107 pp. 397-8.
 108 .SH HISTORY
 109 Written for the FreeS/WAN project by Henry Spencer.
 110 .SH BUGS
 111 If an attempt is made to obtain more than 4e9 bytes
 112 between initializations,
 113 the PRNG will continue to work but
 114 .IR prng_count 's
 115 output will stick at
 116 .BR 4000000000 .
 117 Fixing this would require a longer integer type and does
 118 not seem worth the trouble,
 119 since you should probably re-initialize before then anyway...
 120 .PP
 121 ``RC4'' is a trademark of RSA Data Security, Inc.