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