Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / RAND_egd.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
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'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
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' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
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
984263bc 79'br\}
74dab6c2
JR
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"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH RAND_egd 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
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
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
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'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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'
74dab6c2
JR
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'\*(#]
984263bc
MD
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
74dab6c2
JR
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
984263bc
MD
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'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
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
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191RAND_egd \- query entropy gathering daemon
192.SH "SYNOPSIS"
74dab6c2 193.PP
984263bc
MD
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"
74dab6c2 205\fIRAND_egd()\fR queries the entropy gathering daemon EGD on socket \fBpath\fR.
984263bc 206It queries 255 bytes and uses RAND_add(3) to seed the
74dab6c2
JR
207OpenSSL built-in PRNG. \fIRAND_egd\fR\|(path) is a wrapper for
208\fIRAND_egd_bytes\fR\|(path, 255);
984263bc 209.PP
74dab6c2 210\fIRAND_egd_bytes()\fR queries the entropy gathering daemon EGD on socket \fBpath\fR.
984263bc 211It queries \fBbytes\fR bytes and uses RAND_add(3) to seed the
74dab6c2 212OpenSSL built-in PRNG.
984263bc
MD
213This function is more flexible than \fIRAND_egd()\fR.
214When only one secret key must
215be generated, it is not necessary to request the full amount 255 bytes from
74dab6c2
JR
216the EGD socket. This can be advantageous, since the amount of entropy
217that can be retrieved from EGD over time is limited.
984263bc 218.PP
74dab6c2
JR
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
222OpenSSL built-in PRNG using RAND_add(3).
984263bc 223.SH "NOTES"
984263bc 224On systems without /dev/*random devices providing entropy from the kernel,
74dab6c2 225the EGD entropy gathering daemon can be used to collect entropy. It provides
984263bc
MD
226a socket interface through which entropy can be gathered in chunks up to
227255 bytes. Several chunks can be queried during one connection.
228.PP
74dab6c2
JR
229EGD is available from http://www.lothar.com/tech/crypto/ (\f(CWperl
230Makefile.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
233random bytes that EGD has collected. The read is performed in
984263bc
MD
234non-blocking mode.
235.PP
74dab6c2 236Alternatively, the EGD\-interface compatible daemon PRNGD can be used. It is
984263bc
MD
237available from
238http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html .
74dab6c2 239PRNGD does employ an internal PRNG itself and can therefore never run
984263bc
MD
240out of entropy.
241.PP
74dab6c2 242OpenSSL automatically queries EGD when entropy is requested via \fIRAND_bytes()\fR
984263bc
MD
243or the status is checked via \fIRAND_status()\fR for the first time, if the socket
244is located at /var/run/egd-pool, /dev/egd-pool or /etc/egd-pool.
245.SH "RETURN VALUE"
74dab6c2 246\fIRAND_egd()\fR and \fIRAND_egd_bytes()\fR return the number of bytes read from the
984263bc 247daemon on success, and \-1 if the connection failed or the daemon did not
74dab6c2 248return enough data to fully seed the PRNG.
984263bc 249.PP
74dab6c2
JR
250\fIRAND_query_egd_bytes()\fR returns the number of bytes read from the daemon on
251success, and \-1 if the connection failed. The PRNG state is not considered.
984263bc 252.SH "SEE ALSO"
984263bc
MD
253rand(3), RAND_add(3),
254RAND_cleanup(3)
255.SH "HISTORY"
74dab6c2 256\fIRAND_egd()\fR is available since OpenSSL 0.9.5.
984263bc 257.PP
74dab6c2 258\fIRAND_egd_bytes()\fR is available since OpenSSL 0.9.6.
984263bc 259.PP
74dab6c2 260\fIRAND_query_egd_bytes()\fR is available since OpenSSL 0.9.7.
984263bc
MD
261.PP
262The automatic query of /var/run/egd-pool et al was added in OpenSSL 0.9.7.
74dab6c2
JR
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