Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libcrypto / man / RAND_add.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
8b0cefbb 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
8b0cefbb 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
8b0cefbb 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
8b0cefbb
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
8b0cefbb 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
8b0cefbb
JR
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
984263bc
MD
35'br\}
36.el\{\
8b0cefbb
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 41'br\}
8b0cefbb 42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
8b0cefbb 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
8b0cefbb
JR
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
8b0cefbb
JR
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 54..
8b0cefbb
JR
55. nr % 0
56. rr F
984263bc 57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
8b0cefbb
JR
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
984263bc 66.if n \{\
8b0cefbb
JR
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
984263bc
MD
72.\}
73.if t \{\
8b0cefbb
JR
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
984263bc 79.\}
8b0cefbb 80. \" simple accents for nroff and troff
984263bc 81.if n \{\
8b0cefbb
JR
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
984263bc
MD
88.\}
89.if t \{\
8b0cefbb
JR
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 96.\}
8b0cefbb 97. \" troff and (daisy-wheel) nroff accents
984263bc
MD
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 107. \" corrections for vroff
984263bc
MD
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 110. \" for low resolution devices (crt and lpr)
984263bc
MD
111.if \n(.H>23 .if \n(.V>19 \
112\{\
8b0cefbb
JR
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
984263bc
MD
122.\}
123.rm #[ #] #H #V #F C
8b0cefbb
JR
124.\" ========================================================================
125.\"
126.IX Title "RAND_add 3"
e3261593 127.TH RAND_add 3 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
984263bc
MD
132.SH "NAME"
133RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen \- add
74dab6c2 134entropy to the PRNG
984263bc 135.SH "SYNOPSIS"
8b0cefbb 136.IX Header "SYNOPSIS"
984263bc
MD
137.Vb 1
138\& #include <openssl/rand.h>
e257b235 139\&
984263bc 140\& void RAND_seed(const void *buf, int num);
e257b235 141\&
984263bc 142\& void RAND_add(const void *buf, int num, double entropy);
e257b235 143\&
984263bc 144\& int RAND_status(void);
e257b235 145\&
984263bc
MD
146\& int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam);
147\& void RAND_screen(void);
148.Ve
149.SH "DESCRIPTION"
8b0cefbb
JR
150.IX Header "DESCRIPTION"
151\&\fIRAND_add()\fR mixes the \fBnum\fR bytes at \fBbuf\fR into the \s-1PRNG\s0 state. Thus,
984263bc 152if the data at \fBbuf\fR are unpredictable to an adversary, this
8b0cefbb 153increases the uncertainty about the state and makes the \s-1PRNG\s0 output
984263bc
MD
154less predictable. Suitable input comes from user interaction (random
155key presses, mouse movements) and certain hardware events. The
8b0cefbb 156\&\fBentropy\fR argument is (the lower bound of) an estimate of how much
984263bc
MD
157randomness is contained in \fBbuf\fR, measured in bytes. Details about
158sources of randomness and how to estimate their entropy can be found
8b0cefbb 159in the literature, e.g. \s-1RFC\s0 1750.
984263bc 160.PP
8b0cefbb
JR
161\&\fIRAND_add()\fR may be called with sensitive data such as user entered
162passwords. The seed values cannot be recovered from the \s-1PRNG\s0 output.
984263bc 163.PP
8b0cefbb
JR
164OpenSSL makes sure that the \s-1PRNG\s0 state is unique for each thread. On
165systems that provide \f(CW\*(C`/dev/urandom\*(C'\fR, the randomness device is used
166to seed the \s-1PRNG\s0 transparently. However, on all other systems, the
167application is responsible for seeding the \s-1PRNG\s0 by calling \fIRAND_add()\fR,
168\&\fIRAND_egd\fR\|(3)
169or \fIRAND_load_file\fR\|(3).
984263bc 170.PP
8b0cefbb 171\&\fIRAND_seed()\fR is equivalent to \fIRAND_add()\fR when \fBnum == entropy\fR.
984263bc 172.PP
8b0cefbb 173\&\fIRAND_event()\fR collects the entropy from Windows events such as mouse
984263bc 174movements and other user interaction. It should be called with the
8b0cefbb 175\&\fBiMsg\fR, \fBwParam\fR and \fBlParam\fR arguments of \fIall\fR messages sent to
984263bc 176the window procedure. It will estimate the entropy contained in the
8b0cefbb 177event message (if any), and add it to the \s-1PRNG\s0. The program can then
984263bc
MD
178process the messages as usual.
179.PP
180The \fIRAND_screen()\fR function is available for the convenience of Windows
8b0cefbb
JR
181programmers. It adds the current contents of the screen to the \s-1PRNG\s0.
182For applications that can catch Windows events, seeding the \s-1PRNG\s0 by
984263bc
MD
183calling \fIRAND_event()\fR is a significantly better source of
184randomness. It should be noted that both methods cannot be used on
185servers that run without user interaction.
186.SH "RETURN VALUES"
8b0cefbb
JR
187.IX Header "RETURN VALUES"
188\&\fIRAND_status()\fR and \fIRAND_event()\fR return 1 if the \s-1PRNG\s0 has been seeded
984263bc
MD
189with enough data, 0 otherwise.
190.PP
191The other functions do not return values.
192.SH "SEE ALSO"
8b0cefbb
JR
193.IX Header "SEE ALSO"
194\&\fIrand\fR\|(3), \fIRAND_egd\fR\|(3),
195\&\fIRAND_load_file\fR\|(3), \fIRAND_cleanup\fR\|(3)
984263bc 196.SH "HISTORY"
8b0cefbb
JR
197.IX Header "HISTORY"
198\&\fIRAND_seed()\fR and \fIRAND_screen()\fR are available in all versions of SSLeay
984263bc
MD
199and OpenSSL. \fIRAND_add()\fR and \fIRAND_status()\fR have been added in OpenSSL
2000.9.5, \fIRAND_event()\fR in OpenSSL 0.9.5a.