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