doc/manpage.d/ipsec_prng_bytes.3.html

   1 Content-type: text/html
   2
   3 <HTML><HEAD><TITLE>Manpage of IPSEC_PRNG</TITLE>
   4 </HEAD><BODY>
   5 <H1>IPSEC_PRNG</H1>
   6 Section: C Library Functions (3)<BR>Updated: 1 April 2002<BR><A HREF="#index">Index</A>
   7 <A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
   8
   9
  10 <A NAME="lbAB">&nbsp;</A>
  11 <H2>NAME</H2>
  12
  13 ipsec prng_init - initialize IPsec pseudorandom-number generator
  14 <BR>
  15
  16 ipsec prng_bytes - get bytes from IPsec pseudorandom-number generator
  17 <BR>
  18
  19 ipsec prng_final - close down IPsec pseudorandom-number generator
  20 <A NAME="lbAC">&nbsp;</A>
  21 <H2>SYNOPSIS</H2>
  22
  23 <B>#include &lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
  24
  25 <P>
  26 <B>void prng_init(struct prng *prng,</B>
  27
  28 <BR>
  29 &nbsp;
  30 <B>const unsigned char *key, size_t keylen);</B>
  31
  32 <BR>
  33
  34 <B>void prng_bytes(struct prng *prng, char *dst,</B>
  35
  36 <BR>
  37 &nbsp;
  38 <B>size_t dstlen);</B>
  39
  40 <BR>
  41
  42 <B>unsigned long prng_count(struct prng *prng);</B>
  43
  44 <BR>
  45
  46 <B>void prng_final(struct prng *prng);</B>
  47
  48 <A NAME="lbAD">&nbsp;</A>
  49 <H2>DESCRIPTION</H2>
  50
  51 <I>Prng_init</I>
  52
  53 initializes a crypto-quality pseudo-random-number generator from a key;
  54 <I>prng_bytes</I>
  55
  56 obtains pseudo-random bytes from it;
  57 <I>prng_count</I>
  58
  59 reports the number of bytes extracted from it to date;
  60 <I>prng_final</I>
  61
  62 closes it down.
  63 It is the user's responsibility to initialize a PRNG before using it,
  64 and not to use it again after it is closed down.
  65 <P>
  66
  67 <I>Prng_init</I>
  68
  69 initializes,
  70 or re-initializes,
  71 the specified
  72 <I>prng</I>
  73
  74 from the
  75 <I>key</I>,
  76
  77 whose length is given by
  78 <I>keylen</I>.
  79
  80 The user must allocate the
  81 <B>struct prng</B>
  82
  83 pointed to by
  84 <I>prng</I>.
  85
  86 There is no particular constraint on the length of the key,
  87 although a key longer than 256 bytes is unnecessary because
  88 only the first 256 would be used.
  89 Initialization requires on the order of 3000 integer operations,
  90 independent of key length.
  91 <P>
  92
  93 <I>Prng_bytes</I>
  94
  95 obtains
  96 <I>dstlen</I>
  97
  98 pseudo-random bytes from the PRNG and puts them in
  99 <I>buf</I>.
 100
 101 This is quite fast,
 102 on the order of 10 integer operations per byte.
 103 <P>
 104
 105 <I>Prng_count</I>
 106
 107 reports the number of bytes obtained from the PRNG
 108 since it was (last) initialized.
 109 <P>
 110
 111 <I>Prng_final</I>
 112
 113 closes down a PRNG by
 114 zeroing its internal memory,
 115 obliterating all trace of the state used to generate its previous output.
 116 This requires on the order of 250 integer operations.
 117 <P>
 118
 119 The
 120 <B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
 121
 122 header file supplies the definition of the
 123 <B>prng</B>
 124
 125 structure.
 126 Examination of its innards is discouraged, as they may change.
 127 <P>
 128
 129 The PRNG algorithm
 130 used by these functions is currently identical to that of RC4(TM).
 131 This algorithm is cryptographically strong,
 132 sufficiently unpredictable that even a hostile observer will
 133 have difficulty determining the next byte of output from past history,
 134 provided it is initialized from a reasonably large key composed of
 135 highly random bytes (see
 136 <I><A HREF="random.4.html">random</A></I>(4)).
 137
 138 The usual run of software pseudo-random-number generators
 139 (e.g.
 140 <I><A HREF="random.3.html">random</A></I>(3))
 141
 142 are
 143 <I>not</I>
 144
 145 cryptographically strong.
 146 <P>
 147
 148 The well-known attacks against RC4(TM),
 149 e.g. as found in 802.11b's WEP encryption system,
 150 apply only if multiple PRNGs are initialized with closely-related keys
 151 (e.g., using a counter appended to a base key).
 152 If such keys are used, the first few hundred pseudo-random bytes
 153 from each PRNG should be discarded,
 154 to give the PRNGs a chance to randomize their innards properly.
 155 No useful attacks are known if the key is well randomized to begin with.
 156 <A NAME="lbAE">&nbsp;</A>
 157 <H2>SEE ALSO</H2>
 158
 159 <A HREF="random.3.html">random</A>(3), <A HREF="random.4.html">random</A>(4)
 160 <BR>
 161
 162 Bruce Schneier,
 163 <I>Applied Cryptography</I>, 2nd ed., 1996, ISBN 0-471-11709-9,
 164 pp. 397-8.
 165 <A NAME="lbAF">&nbsp;</A>
 166 <H2>HISTORY</H2>
 167
 168 Written for the FreeS/WAN project by Henry Spencer.
 169 <A NAME="lbAG">&nbsp;</A>
 170 <H2>BUGS</H2>
 171
 172 If an attempt is made to obtain more than 4e9 bytes
 173 between initializations,
 174 the PRNG will continue to work but
 175 <I>prng_count</I>'s
 176
 177 output will stick at
 178 <B>4000000000</B>.
 179
 180 Fixing this would require a longer integer type and does
 181 not seem worth the trouble,
 182 since you should probably re-initialize before then anyway...
 183 <P>
 184
 185 ``RC4'' is a trademark of RSA Data Security, Inc.
 186 <P>
 187
 188 <HR>
 189 <A NAME="index">&nbsp;</A><H2>Index</H2>
 190 <DL>
 191 <DT><A HREF="#lbAB">NAME</A><DD>
 192 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
 193 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
 194 <DT><A HREF="#lbAE">SEE ALSO</A><DD>
 195 <DT><A HREF="#lbAF">HISTORY</A><DD>
 196 <DT><A HREF="#lbAG">BUGS</A><DD>
 197 </DL>
 198 <HR>
 199 This document was created by
 200 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
 201 using the manual pages.<BR>
 202 Time: 21:40:18 GMT, November 11, 2003
 203 </BODY>
 204 </HTML>