Upgrade to OpenSSL 0.9.8h.
[dragonfly.git] / secure / lib / libcrypto / man / rand.3
CommitLineData
aac4ff6f 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
8b0cefbb 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
8b0cefbb
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
aac4ff6f
PA
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
32.tr \(*W-|\(bv\*(Tr
8b0cefbb 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
8b0cefbb
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
8b0cefbb
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
8b0cefbb
JR
59. nr % 0
60. rr F
984263bc 61.\}
8b0cefbb 62.\"
aac4ff6f
PA
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
8b0cefbb
JR
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
984263bc 71.if n \{\
8b0cefbb
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
8b0cefbb
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
8b0cefbb 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
8b0cefbb
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
8b0cefbb
JR
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 101.\}
8b0cefbb 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 112. \" corrections for vroff
984263bc
MD
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
8b0cefbb
JR
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
8b0cefbb
JR
129.\" ========================================================================
130.\"
131.IX Title "rand 3"
aac4ff6f 132.TH rand 3 "2008-09-06" "0.9.8h" "OpenSSL"
984263bc 133.SH "NAME"
8b0cefbb 134rand \- pseudo\-random number generator
984263bc 135.SH "SYNOPSIS"
8b0cefbb 136.IX Header "SYNOPSIS"
984263bc
MD
137.Vb 1
138\& #include <openssl/rand.h>
aac4ff6f
PA
139.Ve
140.PP
141.Vb 1
984263bc 142\& int RAND_set_rand_engine(ENGINE *engine);
aac4ff6f
PA
143.Ve
144.PP
145.Vb 2
984263bc
MD
146\& int RAND_bytes(unsigned char *buf, int num);
147\& int RAND_pseudo_bytes(unsigned char *buf, int num);
aac4ff6f
PA
148.Ve
149.PP
150.Vb 3
984263bc
MD
151\& void RAND_seed(const void *buf, int num);
152\& void RAND_add(const void *buf, int num, int entropy);
153\& int RAND_status(void);
aac4ff6f
PA
154.Ve
155.PP
156.Vb 3
984263bc
MD
157\& int RAND_load_file(const char *file, long max_bytes);
158\& int RAND_write_file(const char *file);
159\& const char *RAND_file_name(char *file, size_t num);
aac4ff6f
PA
160.Ve
161.PP
162.Vb 1
984263bc 163\& int RAND_egd(const char *path);
aac4ff6f
PA
164.Ve
165.PP
166.Vb 3
984263bc
MD
167\& void RAND_set_rand_method(const RAND_METHOD *meth);
168\& const RAND_METHOD *RAND_get_rand_method(void);
169\& RAND_METHOD *RAND_SSLeay(void);
aac4ff6f
PA
170.Ve
171.PP
172.Vb 1
984263bc 173\& void RAND_cleanup(void);
aac4ff6f
PA
174.Ve
175.PP
176.Vb 3
984263bc
MD
177\& /* For Win32 only */
178\& void RAND_screen(void);
179\& int RAND_event(UINT, WPARAM, LPARAM);
180.Ve
181.SH "DESCRIPTION"
8b0cefbb
JR
182.IX Header "DESCRIPTION"
183Since the introduction of the \s-1ENGINE\s0 \s-1API\s0, the recommended way of controlling
184default implementations is by using the \s-1ENGINE\s0 \s-1API\s0 functions. The default
185\&\fB\s-1RAND_METHOD\s0\fR, as set by \fIRAND_set_rand_method()\fR and returned by
186\&\fIRAND_get_rand_method()\fR, is only used if no \s-1ENGINE\s0 has been set as the default
187\&\*(L"rand\*(R" implementation. Hence, these two functions are no longer the recommened
984263bc
MD
188way to control defaults.
189.PP
8b0cefbb
JR
190If an alternative \fB\s-1RAND_METHOD\s0\fR implementation is being used (either set
191directly or as provided by an \s-1ENGINE\s0 module), then it is entirely responsible
192for the generation and management of a cryptographically secure \s-1PRNG\s0 stream. The
193mechanisms described below relate solely to the software \s-1PRNG\s0 implementation
984263bc
MD
194built in to OpenSSL and used by default.
195.PP
196These functions implement a cryptographically secure pseudo-random
8b0cefbb 197number generator (\s-1PRNG\s0). It is used by other library functions for
984263bc
MD
198example to generate random keys, and applications can use it when they
199need randomness.
200.PP
8b0cefbb 201A cryptographic \s-1PRNG\s0 must be seeded with unpredictable data such as
984263bc 202mouse movements or keys pressed at random by the user. This is
8b0cefbb
JR
203described in \fIRAND_add\fR\|(3). Its state can be saved in a seed file
204(see \fIRAND_load_file\fR\|(3)) to avoid having to go through the
984263bc
MD
205seeding process whenever the application is started.
206.PP
8b0cefbb 207\&\fIRAND_bytes\fR\|(3) describes how to obtain random data from the
aac4ff6f 208\&\s-1PRNG\s0.
984263bc 209.SH "INTERNALS"
8b0cefbb
JR
210.IX Header "INTERNALS"
211The \fIRAND_SSLeay()\fR method implements a \s-1PRNG\s0 based on a cryptographic
984263bc
MD
212hash function.
213.PP
214The following description of its design is based on the SSLeay
215documentation:
216.PP
8b0cefbb 217First up I will state the things I believe I need for a good \s-1RNG\s0.
aac4ff6f
PA
218.IP "1" 4
219.IX Item "1"
8b0cefbb 220A good hashing algorithm to mix things up and to convert the \s-1RNG\s0 'state'
984263bc 221to random numbers.
aac4ff6f
PA
222.IP "2" 4
223.IX Item "2"
8b0cefbb 224An initial source of random 'state'.
aac4ff6f
PA
225.IP "3" 4
226.IX Item "3"
984263bc
MD
227The state should be very large. If the \s-1RNG\s0 is being used to generate
2284096 bit \s-1RSA\s0 keys, 2 2048 bit random strings are required (at a minimum).
229If your \s-1RNG\s0 state only has 128 bits, you are obviously limiting the
230search space to 128 bits, not 2048. I'm probably getting a little
231carried away on this last point but it does indicate that it may not be
232a bad idea to keep quite a lot of \s-1RNG\s0 state. It should be easier to
233break a cipher than guess the \s-1RNG\s0 seed data.
aac4ff6f
PA
234.IP "4" 4
235.IX Item "4"
984263bc
MD
236Any \s-1RNG\s0 seed data should influence all subsequent random numbers
237generated. This implies that any random seed data entered will have
238an influence on all subsequent random numbers generated.
aac4ff6f
PA
239.IP "5" 4
240.IX Item "5"
984263bc
MD
241When using data to seed the \s-1RNG\s0 state, the data used should not be
242extractable from the \s-1RNG\s0 state. I believe this should be a
8b0cefbb 243requirement because one possible source of 'secret' semi random
984263bc
MD
244data would be a private key or a password. This data must
245not be disclosed by either subsequent random numbers or a
8b0cefbb 246\&'core' dump left by a program crash.
aac4ff6f
PA
247.IP "6" 4
248.IX Item "6"
8b0cefbb 249Given the same initial 'state', 2 systems should deviate in their \s-1RNG\s0 state
984263bc 250(and hence the random numbers generated) over time if at all possible.
aac4ff6f
PA
251.IP "7" 4
252.IX Item "7"
984263bc
MD
253Given the random number output stream, it should not be possible to determine
254the \s-1RNG\s0 state or the next random number.
255.PP
256The algorithm is as follows.
257.PP
8b0cefbb 258There is global state made up of a 1023 byte buffer (the 'state'), a
984263bc
MD
259working hash value ('md'), and a counter ('count').
260.PP
8b0cefbb 261Whenever seed data is added, it is inserted into the 'state' as
984263bc
MD
262follows.
263.PP
264The input is chopped up into units of 20 bytes (or less for
265the last block). Each of these blocks is run through the hash
266function as follows: The data passed to the hash function
8b0cefbb 267is the current 'md', the same number of bytes from the 'state'
984263bc 268(the location determined by in incremented looping index) as
8b0cefbb 269the current 'block', the new key data 'block', and 'count'
984263bc 270(which is incremented after each use).
8b0cefbb
JR
271The result of this is kept in 'md' and also xored into the
272\&'state' at the same locations that were used as input into the
984263bc
MD
273hash function. I
274believe this system addresses points 1 (hash function; currently
8b0cefbb 275\&\s-1SHA\-1\s0), 3 (the 'state'), 4 (via the 'md'), 5 (by the use of a hash
984263bc
MD
276function and xor).
277.PP
278When bytes are extracted from the \s-1RNG\s0, the following process is used.
279For each group of 10 bytes (or less), we do the following:
280.PP
8b0cefbb
JR
281Input into the hash function the local 'md' (which is initialized from
282the global 'md' before any bytes are generated), the bytes that are to
283be overwritten by the random bytes, and bytes from the 'state'
984263bc 284(incrementing looping index). From this digest output (which is kept
8b0cefbb
JR
285in 'md'), the top (up to) 10 bytes are returned to the caller and the
286bottom 10 bytes are xored into the 'state'.
984263bc 287.PP
8b0cefbb
JR
288Finally, after we have finished 'num' random bytes for the caller,
289\&'count' (which is incremented) and the local and global 'md' are fed
290into the hash function and the results are kept in the global 'md'.
984263bc 291.PP
8b0cefbb
JR
292I believe the above addressed points 1 (use of \s-1SHA\-1\s0), 6 (by hashing
293into the 'state' the 'old' data from the caller that is about to be
984263bc 294overwritten) and 7 (by not using the 10 bytes given to the caller to
8b0cefbb 295update the 'state', but they are used to update 'md').
984263bc
MD
296.PP
297So of the points raised, only 2 is not addressed (but see
8b0cefbb 298\&\fIRAND_add\fR\|(3)).
984263bc 299.SH "SEE ALSO"
74dab6c2 300.IX Header "SEE ALSO"
8b0cefbb
JR
301\&\fIBN_rand\fR\|(3), \fIRAND_add\fR\|(3),
302\&\fIRAND_load_file\fR\|(3), \fIRAND_egd\fR\|(3),
303\&\fIRAND_bytes\fR\|(3),
304\&\fIRAND_set_rand_method\fR\|(3),
aac4ff6f 305\&\fIRAND_cleanup\fR\|(3)