[thirdparty/strongswan.git] / doc / manpage.d / ipsec_prng_bytes.3.html

Content-type: text/html

<HTML><HEAD><TITLE>Manpage of IPSEC_PRNG</TITLE>
</HEAD><BODY>
<H1>IPSEC_PRNG</H1>
Section: C Library Functions (3)<BR>Updated: 1 April 2002<BR><A HREF="#index">Index</A>
<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>


<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>

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
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>

<B>#include &lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>

<P>
<B>void prng_init(struct prng *prng,</B>

<BR>
&nbsp;
<B>const unsigned char *key, size_t keylen);</B>

<BR>

<B>void prng_bytes(struct prng *prng, char *dst,</B>

<BR>
&nbsp;
<B>size_t dstlen);</B>

<BR>

<B>unsigned long prng_count(struct prng *prng);</B>

<BR>

<B>void prng_final(struct prng *prng);</B>

<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>

<I>Prng_init</I>

initializes a crypto-quality pseudo-random-number generator from a key;
<I>prng_bytes</I>

obtains pseudo-random bytes from it;
<I>prng_count</I>

reports the number of bytes extracted from it to date;
<I>prng_final</I>

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.
<P>

<I>Prng_init</I>

initializes,
or re-initializes,
the specified
<I>prng</I>

from the
<I>key</I>,

whose length is given by
<I>keylen</I>.

The user must allocate the
<B>struct prng</B>

pointed to by
<I>prng</I>.

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.
<P>

<I>Prng_bytes</I>

obtains
<I>dstlen</I>

pseudo-random bytes from the PRNG and puts them in
<I>buf</I>.

This is quite fast,
on the order of 10 integer operations per byte.
<P>

<I>Prng_count</I>

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

<I>Prng_final</I>

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.
<P>

The
<B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>

header file supplies the definition of the
<B>prng</B>

structure.
Examination of its innards is discouraged, as they may change.
<P>

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
<I><A HREF="random.4.html">random</A></I>(4)).

The usual run of software pseudo-random-number generators
(e.g.
<I><A HREF="random.3.html">random</A></I>(3))

are
<I>not</I>

cryptographically strong.
<P>

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.
<A NAME="lbAE">&nbsp;</A>
<H2>SEE ALSO</H2>

<A HREF="random.3.html">random</A>(3), <A HREF="random.4.html">random</A>(4)
<BR>

Bruce Schneier,
<I>Applied Cryptography</I>, 2nd ed., 1996, ISBN 0-471-11709-9,
pp. 397-8.
<A NAME="lbAF">&nbsp;</A>
<H2>HISTORY</H2>

Written for the FreeS/WAN project by Henry Spencer.
<A NAME="lbAG">&nbsp;</A>
<H2>BUGS</H2>

If an attempt is made to obtain more than 4e9 bytes
between initializations,
the PRNG will continue to work but
<I>prng_count</I>'s

output will stick at
<B>4000000000</B>.

Fixing this would require a longer integer type and does
not seem worth the trouble,
since you should probably re-initialize before then anyway...
<P>

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

<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">SEE ALSO</A><DD>
<DT><A HREF="#lbAF">HISTORY</A><DD>
<DT><A HREF="#lbAG">BUGS</A><DD>
</DL>
<HR>
This document was created by
<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 21:40:18 GMT, November 11, 2003
</BODY>
</HTML>
Commit	Line	Data
997358a6 MW	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"> </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"> </A>
	21	<H2>SYNOPSIS</H2>
	22
	23	<B>#include <<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
	24
	25	<P>
	26	<B>void prng_init(struct prng *prng,</B>
	27
	28	<BR>
	29
	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
	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"> </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><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></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"> </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"> </A>
166	<H2>HISTORY</H2>
167
168	Written for the FreeS/WAN project by Henry Spencer.
169	<A NAME="lbAG"> </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"> </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>