Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / RAND_egd.3
1 .rn '' }`
2 ''' $RCSfile$$Revision$$Date$
3 '''
4 ''' $Log$
5 '''
6 .de Sh
7 .br
8 .if t .Sp
9 .ne 5
10 .PP
11 \fB\\$1\fR
12 .PP
13 ..
14 .de Sp
15 .if t .sp .5v
16 .if n .sp
17 ..
18 .de Ip
19 .br
20 .ie \\n(.$>=3 .ne \\$3
21 .el .ne 3
22 .IP "\\$1" \\$2
23 ..
24 .de Vb
25 .ft CW
26 .nf
27 .ne \\$1
28 ..
29 .de Ve
30 .ft R
31
32 .fi
33 ..
34 '''
35 '''
36 '''     Set up \*(-- to give an unbreakable dash;
37 '''     string Tr holds user defined translation string.
38 '''     Bell System Logo is used as a dummy character.
39 '''
40 .tr \(*W-|\(bv\*(Tr
41 .ie n \{\
42 .ds -- \(*W-
43 .ds PI pi
44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46 .ds L" ""
47 .ds R" ""
48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
50 '''   such as .IP and .SH, which do another additional levels of
51 '''   double-quote interpretation
52 .ds M" """
53 .ds S" """
54 .ds N" """""
55 .ds T" """""
56 .ds L' '
57 .ds R' '
58 .ds M' '
59 .ds S' '
60 .ds N' '
61 .ds T' '
62 'br\}
63 .el\{\
64 .ds -- \(em\|
65 .tr \*(Tr
66 .ds L" ``
67 .ds R" ''
68 .ds M" ``
69 .ds S" ''
70 .ds N" ``
71 .ds T" ''
72 .ds L' `
73 .ds R' '
74 .ds M' `
75 .ds S' '
76 .ds N' `
77 .ds T' '
78 .ds PI \(*p
79 'br\}
80 .\"     If the F register is turned on, we'll generate
81 .\"     index entries out stderr for the following things:
82 .\"             TH      Title 
83 .\"             SH      Header
84 .\"             Sh      Subsection 
85 .\"             Ip      Item
86 .\"             X<>     Xref  (embedded
87 .\"     Of course, you have to process the output yourself
88 .\"     in some meaninful fashion.
89 .if \nF \{
90 .de IX
91 .tm Index:\\$1\t\\n%\t"\\$2"
92 ..
93 .nr % 0
94 .rr F
95 .\}
96 .TH RAND_egd 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97 .UC
98 .if n .hy 0
99 .if n .na
100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101 .de CQ          \" put $1 in typewriter font
102 .ft CW
103 'if n "\c
104 'if t \\&\\$1\c
105 'if n \\&\\$1\c
106 'if n \&"
107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108 '.ft R
109 ..
110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111 .       \" AM - accent mark definitions
112 .bd B 3
113 .       \" fudge factors for nroff and troff
114 .if n \{\
115 .       ds #H 0
116 .       ds #V .8m
117 .       ds #F .3m
118 .       ds #[ \f1
119 .       ds #] \fP
120 .\}
121 .if t \{\
122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123 .       ds #V .6m
124 .       ds #F 0
125 .       ds #[ \&
126 .       ds #] \&
127 .\}
128 .       \" simple accents for nroff and troff
129 .if n \{\
130 .       ds ' \&
131 .       ds ` \&
132 .       ds ^ \&
133 .       ds , \&
134 .       ds ~ ~
135 .       ds ? ?
136 .       ds ! !
137 .       ds /
138 .       ds q
139 .\}
140 .if t \{\
141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
150 .\}
151 .       \" troff and (daisy-wheel) nroff accents
152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163 .ds ae a\h'-(\w'a'u*4/10)'e
164 .ds Ae A\h'-(\w'A'u*4/10)'E
165 .ds oe o\h'-(\w'o'u*4/10)'e
166 .ds Oe O\h'-(\w'O'u*4/10)'E
167 .       \" corrections for vroff
168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
170 .       \" for low resolution devices (crt and lpr)
171 .if \n(.H>23 .if \n(.V>19 \
172 \{\
173 .       ds : e
174 .       ds 8 ss
175 .       ds v \h'-1'\o'\(aa\(ga'
176 .       ds _ \h'-1'^
177 .       ds . \h'-1'.
178 .       ds 3 3
179 .       ds o a
180 .       ds d- d\h'-1'\(ga
181 .       ds D- D\h'-1'\(hy
182 .       ds th \o'bp'
183 .       ds Th \o'LP'
184 .       ds ae ae
185 .       ds Ae AE
186 .       ds oe oe
187 .       ds Oe OE
188 .\}
189 .rm #[ #] #H #V #F C
190 .SH "NAME"
191 RAND_egd \- query entropy gathering daemon
192 .SH "SYNOPSIS"
193 .PP
194 .Vb 1
195 \& #include <openssl/rand.h>
196 .Ve
197 .Vb 2
198 \& int RAND_egd(const char *path);
199 \& int RAND_egd_bytes(const char *path, int bytes);
200 .Ve
201 .Vb 1
202 \& int RAND_query_egd_bytes(const char *path, unsigned char *buf, int bytes);
203 .Ve
204 .SH "DESCRIPTION"
205 \fIRAND_egd()\fR queries the entropy gathering daemon EGD on socket \fBpath\fR.
206 It queries 255 bytes and uses RAND_add(3) to seed the
207 OpenSSL built-in PRNG. \fIRAND_egd\fR\|(path) is a wrapper for
208 \fIRAND_egd_bytes\fR\|(path, 255);
209 .PP
210 \fIRAND_egd_bytes()\fR queries the entropy gathering daemon EGD on socket \fBpath\fR.
211 It queries \fBbytes\fR bytes and uses RAND_add(3) to seed the
212 OpenSSL built-in PRNG.
213 This function is more flexible than \fIRAND_egd()\fR.
214 When only one secret key must
215 be generated, it is not necessary to request the full amount 255 bytes from
216 the EGD socket. This can be advantageous, since the amount of entropy
217 that can be retrieved from EGD over time is limited.
218 .PP
219 \fIRAND_query_egd_bytes()\fR performs the actual query of the EGD daemon on socket
220 \fBpath\fR. If \fBbuf\fR is given, \fBbytes\fR bytes are queried and written into
221 \fBbuf\fR. If \fBbuf\fR is NULL, \fBbytes\fR bytes are queried and used to seed the
222 OpenSSL built-in PRNG using RAND_add(3).
223 .SH "NOTES"
224 On systems without /dev/*random devices providing entropy from the kernel,
225 the EGD entropy gathering daemon can be used to collect entropy. It provides
226 a socket interface through which entropy can be gathered in chunks up to
227 255 bytes. Several chunks can be queried during one connection.
228 .PP
229 EGD is available from http://www.lothar.com/tech/crypto/ (\f(CWperl
230 Makefile.PL; make; make install\fR to install). It is run as \fBegd\fR
231 \fIpath\fR, where \fIpath\fR is an absolute path designating a socket. When
232 \fIRAND_egd()\fR is called with that path as an argument, it tries to read
233 random bytes that EGD has collected. The read is performed in
234 non-blocking mode.
235 .PP
236 Alternatively, the EGD\-interface compatible daemon PRNGD can be used. It is
237 available from
238 http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html .
239 PRNGD does employ an internal PRNG itself and can therefore never run
240 out of entropy.
241 .PP
242 OpenSSL automatically queries EGD when entropy is requested via \fIRAND_bytes()\fR
243 or the status is checked via \fIRAND_status()\fR for the first time, if the socket
244 is located at /var/run/egd-pool, /dev/egd-pool or /etc/egd-pool.
245 .SH "RETURN VALUE"
246 \fIRAND_egd()\fR and \fIRAND_egd_bytes()\fR return the number of bytes read from the
247 daemon on success, and \-1 if the connection failed or the daemon did not
248 return enough data to fully seed the PRNG.
249 .PP
250 \fIRAND_query_egd_bytes()\fR returns the number of bytes read from the daemon on
251 success, and \-1 if the connection failed. The PRNG state is not considered.
252 .SH "SEE ALSO"
253 rand(3), RAND_add(3),
254 RAND_cleanup(3)
255 .SH "HISTORY"
256 \fIRAND_egd()\fR is available since OpenSSL 0.9.5.
257 .PP
258 \fIRAND_egd_bytes()\fR is available since OpenSSL 0.9.6.
259 .PP
260 \fIRAND_query_egd_bytes()\fR is available since OpenSSL 0.9.7.
261 .PP
262 The automatic query of /var/run/egd-pool et al was added in OpenSSL 0.9.7.
263
264 .rn }` ''
265 .IX Title "RAND_egd 3"
266 .IX Name "RAND_egd - query entropy gathering daemon"
267
268 .IX Header "NAME"
269
270 .IX Header "SYNOPSIS"
271
272 .IX Header "DESCRIPTION"
273
274 .IX Header "NOTES"
275
276 .IX Header "RETURN VALUE"
277
278 .IX Header "SEE ALSO"
279
280 .IX Header "HISTORY"
281