Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libcrypto / man / RAND_egd.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_egd 3"
e3261593 127.TH RAND_egd 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_egd \- query entropy gathering daemon
134.SH "SYNOPSIS"
8b0cefbb 135.IX Header "SYNOPSIS"
984263bc
MD
136.Vb 1
137\& #include <openssl/rand.h>
e257b235 138\&
984263bc
MD
139\& int RAND_egd(const char *path);
140\& int RAND_egd_bytes(const char *path, int bytes);
e257b235 141\&
984263bc
MD
142\& int RAND_query_egd_bytes(const char *path, unsigned char *buf, int bytes);
143.Ve
144.SH "DESCRIPTION"
8b0cefbb
JR
145.IX Header "DESCRIPTION"
146\&\fIRAND_egd()\fR queries the entropy gathering daemon \s-1EGD\s0 on socket \fBpath\fR.
147It queries 255 bytes and uses \fIRAND_add\fR\|(3) to seed the
148OpenSSL built-in \s-1PRNG\s0. RAND_egd(path) is a wrapper for
149RAND_egd_bytes(path, 255);
984263bc 150.PP
8b0cefbb
JR
151\&\fIRAND_egd_bytes()\fR queries the entropy gathering daemon \s-1EGD\s0 on socket \fBpath\fR.
152It queries \fBbytes\fR bytes and uses \fIRAND_add\fR\|(3) to seed the
153OpenSSL built-in \s-1PRNG\s0.
984263bc
MD
154This function is more flexible than \fIRAND_egd()\fR.
155When only one secret key must
156be generated, it is not necessary to request the full amount 255 bytes from
8b0cefbb
JR
157the \s-1EGD\s0 socket. This can be advantageous, since the amount of entropy
158that can be retrieved from \s-1EGD\s0 over time is limited.
984263bc 159.PP
8b0cefbb
JR
160\&\fIRAND_query_egd_bytes()\fR performs the actual query of the \s-1EGD\s0 daemon on socket
161\&\fBpath\fR. If \fBbuf\fR is given, \fBbytes\fR bytes are queried and written into
162\&\fBbuf\fR. If \fBbuf\fR is \s-1NULL\s0, \fBbytes\fR bytes are queried and used to seed the
163OpenSSL built-in \s-1PRNG\s0 using \fIRAND_add\fR\|(3).
984263bc 164.SH "NOTES"
8b0cefbb 165.IX Header "NOTES"
984263bc 166On systems without /dev/*random devices providing entropy from the kernel,
8b0cefbb 167the \s-1EGD\s0 entropy gathering daemon can be used to collect entropy. It provides
984263bc
MD
168a socket interface through which entropy can be gathered in chunks up to
169255 bytes. Several chunks can be queried during one connection.
170.PP
8b0cefbb
JR
171\&\s-1EGD\s0 is available from http://www.lothar.com/tech/crypto/ (\f(CW\*(C`perl
172Makefile.PL; make; make install\*(C'\fR to install). It is run as \fBegd\fR
173\&\fIpath\fR, where \fIpath\fR is an absolute path designating a socket. When
174\&\fIRAND_egd()\fR is called with that path as an argument, it tries to read
e257b235
PA
175random bytes that \s-1EGD\s0 has collected. \fIRAND_egd()\fR retrieves entropy from the
176daemon using the daemon's \*(L"non-blocking read\*(R" command which shall
177be answered immediately by the daemon without waiting for additional
178entropy to be collected. The write and read socket operations in the
179communication are blocking.
984263bc 180.PP
8b0cefbb 181Alternatively, the EGD-interface compatible daemon \s-1PRNGD\s0 can be used. It is
984263bc 182available from
edae4a78 183http://prngd.sourceforge.net/ .
8b0cefbb 184\&\s-1PRNGD\s0 does employ an internal \s-1PRNG\s0 itself and can therefore never run
984263bc
MD
185out of entropy.
186.PP
8b0cefbb 187OpenSSL automatically queries \s-1EGD\s0 when entropy is requested via \fIRAND_bytes()\fR
984263bc 188or the status is checked via \fIRAND_status()\fR for the first time, if the socket
8b0cefbb 189is located at /var/run/egd\-pool, /dev/egd\-pool or /etc/egd\-pool.
984263bc 190.SH "RETURN VALUE"
8b0cefbb
JR
191.IX Header "RETURN VALUE"
192\&\fIRAND_egd()\fR and \fIRAND_egd_bytes()\fR return the number of bytes read from the
984263bc 193daemon on success, and \-1 if the connection failed or the daemon did not
8b0cefbb 194return enough data to fully seed the \s-1PRNG\s0.
984263bc 195.PP
8b0cefbb
JR
196\&\fIRAND_query_egd_bytes()\fR returns the number of bytes read from the daemon on
197success, and \-1 if the connection failed. The \s-1PRNG\s0 state is not considered.
984263bc 198.SH "SEE ALSO"
8b0cefbb
JR
199.IX Header "SEE ALSO"
200\&\fIrand\fR\|(3), \fIRAND_add\fR\|(3),
201\&\fIRAND_cleanup\fR\|(3)
984263bc 202.SH "HISTORY"
8b0cefbb
JR
203.IX Header "HISTORY"
204\&\fIRAND_egd()\fR is available since OpenSSL 0.9.5.
984263bc 205.PP
8b0cefbb 206\&\fIRAND_egd_bytes()\fR is available since OpenSSL 0.9.6.
984263bc 207.PP
8b0cefbb 208\&\fIRAND_query_egd_bytes()\fR is available since OpenSSL 0.9.7.
984263bc 209.PP
8b0cefbb 210The automatic query of /var/run/egd\-pool et al was added in OpenSSL 0.9.7.