IPSEC_PRNG(3)							 IPSEC_PRNG(3)

NAME
       ipsec prng_init - initialize IPsec pseudorandom-number generator
       ipsec prng_bytes - get bytes from IPsec pseudorandom-number generator
       ipsec prng_final - close down IPsec pseudorandom-number generator

SYNOPSIS
       #include <freeswan.h>

       void prng_init(struct prng *prng,
	   const unsigned char *key, size_t keylen);
       void prng_bytes(struct prng *prng, char *dst,
	   size_t dstlen);
       unsigned long prng_count(struct prng *prng);
       void prng_final(struct prng *prng);

DESCRIPTION
       Prng_init  initializes  a crypto-quality pseudo-random-number generator
       from a key; prng_bytes obtains pseudo-random bytes from it;  prng_count
       reports	the  number  of	 bytes	extracted  from it to date; prng_final
       closes it down.	It is the user's responsibility to initialize  a  PRNG
       before using it, and not to use it again after it is closed down.

       Prng_init  initializes,	or re-initializes, the specified prng from the
       key, whose length is given by  keylen.	The  user  must	 allocate  the
       struct  prng  pointed to by prng.  There is no particular constraint on
       the length of the key, although a key longer than 256 bytes is unneces‐
       sary because only the first 256 would be used.  Initialization requires
       on the order of 3000 integer operations, independent of key length.

       Prng_bytes obtains dstlen pseudo-random bytes from the  PRNG  and  puts
       them in buf.  This is quite fast, on the order of 10 integer operations
       per byte.

       Prng_count reports the number of bytes obtained from the PRNG since  it
       was (last) initialized.

       Prng_final  closes down a PRNG by zeroing its internal memory, obliter‐
       ating all trace of the state used  to  generate	its  previous  output.
       This requires on the order of 250 integer operations.

       The <freeswan.h> header file supplies the definition of the prng struc‐
       ture.  Examination of its innards is discouraged, as they may change.

       The PRNG algorithm used by these functions is  currently	 identical  to
       that  of	 RC4(TM).   This algorithm is cryptographically strong, suffi‐
       ciently unpredictable that even a hostile observer will have difficulty
       determining  the	 next byte of output from past history, provided it is
       initialized from a reasonably large key composed of highly random bytes
       (see random(4)).	 The usual run of software pseudo-random-number gener‐
       ators (e.g.  random(3)) are not cryptographically strong.

       The well-known attacks against RC4(TM), e.g. as found in 802.11b's  WEP
       encryption  system,  apply  only if multiple PRNGs are initialized with
       closely-related keys (e.g., using a counter appended to	a  base	 key).
       If  such	 keys are used, the first few hundred pseudo-random bytes from
       each PRNG should be discarded, to give the PRNGs a chance to  randomize
       their innards properly.	No useful attacks are known if the key is well
       randomized to begin with.

SEE ALSO
       random(3), random(4)
       Bruce   Schneier,   Applied   Cryptography,   2nd   ed.,	  1996,	  ISBN
       0-471-11709-9, pp. 397-8.

HISTORY
       Written for the FreeS/WAN project by Henry Spencer.

BUGS
       If an attempt is made to obtain more than 4e9 bytes between initializa‐
       tions, the PRNG will continue to	 work  but  prng_count's  output  will
       stick  at  4000000000.  Fixing this would require a longer integer type
       and does not seem worth the trouble, since you should probably  re-ini‐
       tialize before then anyway...

       ``RC4'' is a trademark of RSA Data Security, Inc.

				 1 April 2002			 IPSEC_PRNG(3)

Vote for polarhome