122 lines
3.5 KiB
Groff
122 lines
3.5 KiB
Groff
.TH IPSEC_PRNG 3 "1 April 2002"
|
|
.\" RCSID $Id: prng.3,v 1.1 2004/03/15 20:35:26 as Exp $
|
|
.SH NAME
|
|
ipsec prng_init \- initialize IPsec pseudorandom-number generator
|
|
.br
|
|
ipsec prng_bytes \- get bytes from IPsec pseudorandom-number generator
|
|
.br
|
|
ipsec prng_final \- close down IPsec pseudorandom-number generator
|
|
.SH SYNOPSIS
|
|
.B "#include <freeswan.h>
|
|
.sp
|
|
.B "void prng_init(struct prng *prng,"
|
|
.ti +1c
|
|
.B "const unsigned char *key, size_t keylen);"
|
|
.br
|
|
.B "void prng_bytes(struct prng *prng, char *dst,"
|
|
.ti +1c
|
|
.B "size_t dstlen);"
|
|
.br
|
|
.B "unsigned long prng_count(struct prng *prng);"
|
|
.br
|
|
.B "void prng_final(struct prng *prng);"
|
|
.SH DESCRIPTION
|
|
.I Prng_init
|
|
initializes a crypto-quality pseudo-random-number generator from a key;
|
|
.I prng_bytes
|
|
obtains pseudo-random bytes from it;
|
|
.I prng_count
|
|
reports the number of bytes extracted from it to date;
|
|
.I 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.
|
|
.PP
|
|
.I Prng_init
|
|
initializes,
|
|
or re-initializes,
|
|
the specified
|
|
.I prng
|
|
from the
|
|
.IR key ,
|
|
whose length is given by
|
|
.IR keylen .
|
|
The user must allocate the
|
|
.B "struct prng"
|
|
pointed to by
|
|
.IR prng .
|
|
There is no particular constraint on the length of the key,
|
|
although a key longer than 256 bytes is unnecessary because
|
|
only the first 256 would be used.
|
|
Initialization requires on the order of 3000 integer operations,
|
|
independent of key length.
|
|
.PP
|
|
.I Prng_bytes
|
|
obtains
|
|
.I dstlen
|
|
pseudo-random bytes from the PRNG and puts them in
|
|
.IR buf .
|
|
This is quite fast,
|
|
on the order of 10 integer operations per byte.
|
|
.PP
|
|
.I Prng_count
|
|
reports the number of bytes obtained from the PRNG
|
|
since it was (last) initialized.
|
|
.PP
|
|
.I Prng_final
|
|
closes down a PRNG by
|
|
zeroing its internal memory,
|
|
obliterating all trace of the state used to generate its previous output.
|
|
This requires on the order of 250 integer operations.
|
|
.PP
|
|
The
|
|
.B <freeswan.h>
|
|
header file supplies the definition of the
|
|
.B prng
|
|
structure.
|
|
Examination of its innards is discouraged, as they may change.
|
|
.PP
|
|
The PRNG algorithm
|
|
used by these functions is currently identical to that of RC4(TM).
|
|
This algorithm is cryptographically strong,
|
|
sufficiently 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
|
|
.IR random (4)).
|
|
The usual run of software pseudo-random-number generators
|
|
(e.g.
|
|
.IR random (3))
|
|
are
|
|
.I not
|
|
cryptographically strong.
|
|
.PP
|
|
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.
|
|
.SH SEE ALSO
|
|
random(3), random(4)
|
|
.br
|
|
Bruce Schneier,
|
|
\fIApplied Cryptography\fR, 2nd ed., 1996, ISBN 0-471-11709-9,
|
|
pp. 397-8.
|
|
.SH HISTORY
|
|
Written for the FreeS/WAN project by Henry Spencer.
|
|
.SH BUGS
|
|
If an attempt is made to obtain more than 4e9 bytes
|
|
between initializations,
|
|
the PRNG will continue to work but
|
|
.IR prng_count 's
|
|
output will stick at
|
|
.BR 4000000000 .
|
|
Fixing this would require a longer integer type and does
|
|
not seem worth the trouble,
|
|
since you should probably re-initialize before then anyway...
|
|
.PP
|
|
``RC4'' is a trademark of RSA Data Security, Inc.
|