| blob | e3193f6fd44124ea5fbecbb9d06fb15235d99ec6 |
1 .\" $OpenBSD: BIO_s_accept.3,v 1.5 2016/12/06 14:45:08 schwarze Exp $
2 .\" OpenSSL c03726ca Thu Aug 27 12:28:08 2015 -0400
3 .\"
4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
5 .\" Copyright (c) 2000, 2014, 2015 The OpenSSL Project. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\"
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\"
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in
16 .\" the documentation and/or other materials provided with the
17 .\" distribution.
18 .\"
19 .\" 3. All advertising materials mentioning features or use of this
20 .\" software must display the following acknowledgment:
21 .\" "This product includes software developed by the OpenSSL Project
22 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23 .\"
24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25 .\" endorse or promote products derived from this software without
26 .\" prior written permission. For written permission, please contact
27 .\" openssl-core@openssl.org.
28 .\"
29 .\" 5. Products derived from this software may not be called "OpenSSL"
30 .\" nor may "OpenSSL" appear in their names without prior written
31 .\" permission of the OpenSSL Project.
32 .\"
33 .\" 6. Redistributions of any form whatsoever must retain the following
34 .\" acknowledgment:
35 .\" "This product includes software developed by the OpenSSL Project
36 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37 .\"
38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
50 .\"
51 .Dd $Mdocdate: December 6 2016 $
52 .Dt BIO_S_ACCEPT 3
53 .Os
54 .Sh NAME
55 .Nm BIO_s_accept ,
56 .Nm BIO_set_accept_port ,
57 .Nm BIO_get_accept_port ,
58 .Nm BIO_new_accept ,
59 .Nm BIO_set_nbio_accept ,
60 .Nm BIO_set_accept_bios ,
61 .Nm BIO_set_bind_mode ,
62 .Nm BIO_get_bind_mode ,
63 .Nm BIO_do_accept
64 .Nd accept BIO
65 .Sh SYNOPSIS
66 .In openssl/bio.h
67 .Ft BIO_METHOD *
68 .Fo BIO_s_accept
69 .Fa void
70 .Fc
71 .Ft long
72 .Fo BIO_set_accept_port
73 .Fa "BIO *b"
74 .Fa "char *name"
75 .Fc
76 .Ft char *
77 .Fo BIO_get_accept_port
78 .Fa "BIO *b"
79 .Fc
80 .Ft BIO *
81 .Fo BIO_new_accept
82 .Fa "char *host_port"
83 .Fc
84 .Ft long
85 .Fo BIO_set_nbio_accept
86 .Fa "BIO *b"
87 .Fa "int n"
88 .Fc
89 .Ft long
90 .Fo BIO_set_accept_bios
91 .Fa "BIO *b"
92 .Fa "char *bio"
93 .Fc
94 .Ft long
95 .Fo BIO_set_bind_mode
96 .Fa "BIO *b"
97 .Fa "long mode"
98 .Fc
99 .Ft long
100 .Fo BIO_get_bind_mode
101 .Fa "BIO *b"
102 .Fa "long dummy"
103 .Fc
104 .Fd #define BIO_BIND_NORMAL 0
105 .Fd #define BIO_BIND_REUSEADDR_IF_UNUSED 1
106 .Fd #define BIO_BIND_REUSEADDR 2
107 .Ft int
108 .Fo BIO_do_accept
109 .Fa "BIO *b"
110 .Fc
111 .Sh DESCRIPTION
112 .Fn BIO_s_accept
113 returns the accept BIO method.
114 This is a wrapper round the platform's TCP/IP socket
115 .Xr accept 2
116 routines.
117 .Pp
118 Using accept BIOs, TCP/IP connections can be accepted
119 and data transferred using only BIO routines.
120 In this way any platform specific operations
121 are hidden by the BIO abstraction.
122 .Pp
123 Read and write operations on an accept BIO
124 will perform I/O on the underlying connection.
125 If no connection is established and the port (see below) is set up
126 properly then the BIO waits for an incoming connection.
127 .Pp
128 Accept BIOs support
129 .Xr BIO_puts 3
130 but not
131 .Xr BIO_gets 3 .
132 .Pp
133 If the close flag is set on an accept BIO, then any active
134 connection on that chain is shut down and the socket closed when
135 the BIO is freed.
136 .Pp
137 Calling
138 .Xr BIO_reset 3
139 on an accept BIO will close any active connection and reset the BIO
140 into a state where it awaits another incoming connection.
141 .Pp
142 .Xr BIO_get_fd 3
143 and
144 .Xr BIO_set_fd 3
145 can be called to retrieve or set the accept socket.
146 See
147 .Xr BIO_s_fd 3 .
148 .Pp
149 .Fn BIO_set_accept_port
150 uses the string
151 .Fa name
152 to set the accept port.
153 The port is represented as a string of the form
154 .Ar host : Ns Ar port ,
155 where
156 .Ar host
157 is the interface to use and
158 .Ar port
159 is the port.
160 The host can be
161 .Qq * ,
162 which is interpreted as meaning any interface;
163 .Ar port
164 has the same syntax as the port specified in
165 .Xr BIO_set_conn_port 3
166 for connect BIOs.
167 It can be a numerical port string or a string to look up using
168 .Xr getservbyname 3
169 and a string table.
170 .Pp
171 .Fn BIO_new_accept
172 combines
173 .Xr BIO_new 3
174 and
175 .Fn BIO_set_accept_port
176 into a single call.
177 It creates a new accept BIO with port
178 .Fa host_port .
179 .Pp
180 .Fn BIO_set_nbio_accept
181 sets the accept socket to blocking mode (the default) if
182 .Fa n
183 is 0 or non-blocking mode if
184 .Fa n
185 is 1.
186 .Pp
187 .Fn BIO_set_accept_bios
188 can be used to set a chain of BIOs which will be duplicated
189 and prepended to the chain when an incoming connection is received.
190 This is useful if, for example, a buffering or SSL BIO
191 is required for each connection.
192 The chain of BIOs must not be freed after this call -
193 they will be automatically freed when the accept BIO is freed.
194 .Pp
195 .Fn BIO_set_bind_mode
196 and
197 .Fn BIO_get_bind_mode
198 set and retrieve the current bind mode.
199 If
200 .Dv BIO_BIND_NORMAL Pq the default
201 is set, then another socket cannot be bound to the same port.
202 If
203 .Dv BIO_BIND_REUSEADDR
204 is set, then other sockets can bind to the same port.
205 If
206 .Dv BIO_BIND_REUSEADDR_IF_UNUSED
207 is set, then an attempt is first made to use
208 .Dv BIO_BIN_NORMAL ;
209 if this fails and the port is not in use,
210 then a second attempt is made using
211 .Dv BIO_BIND_REUSEADDR .
212 .Pp
213 .Fn BIO_do_accept
214 serves two purposes.
215 When it is first called, after the accept BIO has been set up,
216 it will attempt to create the accept socket and bind an address to it.
217 Second and subsequent calls to
218 .Fn BIO_do_accept
219 will await an incoming connection, or request a retry in non-blocking mode.
220 .Sh NOTES
221 When an accept BIO is at the end of a chain, it will await an
222 incoming connection before processing I/O calls.
223 When an accept BIO is not at then end of a chain,
224 it passes I/O calls to the next BIO in the chain.
225 .Pp
226 When a connection is established a new socket BIO is created
227 for the connection and appended to the chain.
228 That is the chain is now accept->socket.
229 This effectively means that attempting I/O on an initial accept
230 socket will await an incoming connection then perform I/O on it.
231 .Pp
232 If any additional BIOs have been set using
233 .Fn BIO_set_accept_bios ,
234 then they are placed between the socket and the accept BIO;
235 that is, the chain will be accept->otherbios->socket.
236 .Pp
237 If a server wishes to process multiple connections (as is normally
238 the case), then the accept BIO must be made available for further
239 incoming connections.
240 This can be done by waiting for a connection and then calling:
241 .Pp
242 .Dl connection = BIO_pop(accept);
243 .Pp
244 After this call,
245 .Sy connection
246 will contain a BIO for the recently established connection and
247 .Sy accept
248 will now be a single BIO again which can be used
249 to await further incoming connections.
250 If no further connections will be accepted, the
251 .Sy accept
252 can be freed using
253 .Xr BIO_free 3 .
254 .Pp
255 If only a single connection will be processed,
256 it is possible to perform I/O using the accept BIO itself.
257 This is often undesirable however because the accept BIO
258 will still accept additional incoming connections.
259 This can be resolved by using
260 .Xr BIO_pop 3
261 (see above) and freeing up the accept BIO after the initial connection.
262 .Pp
263 If the underlying accept socket is non-blocking and
264 .Fn BIO_do_accept
265 is called to await an incoming connection, it is possible for
266 .Xr BIO_should_io_special 3
267 with the reason
268 .Dv BIO_RR_ACCEPT .
269 If this happens, then it is an indication that an accept attempt
270 would block: the application should take appropriate action
271 to wait until the underlying socket has accepted a connection
272 and retry the call.
273 .Pp
274 .Fn BIO_set_accept_port ,
275 .Fn BIO_get_accept_port ,
276 .Fn BIO_set_nbio_accept ,
277 .Fn BIO_set_accept_bios ,
278 .Fn BIO_set_bind_mode ,
279 .Fn BIO_get_bind_mode ,
280 and
281 .Fn BIO_do_accept
282 are macros.
283 .Sh RETURN VALUES
284 .Fn BIO_do_accept ,
285 .Fn BIO_set_accept_port ,
286 .Fn BIO_set_nbio_accept ,
287 .Fn BIO_set_accept_bios ,
288 and
289 .Fn BIO_set_bind_mode
290 return 1 for success or 0 or -1 for failure.
291 .Pp
292 .Fn BIO_get_accept_port
293 returns the port as a string or
294 .Dv NULL
295 on error.
296 .Pp
297 .Fn BIO_get_bind_mode
298 returns the set of BIO_BIND flags or -1 on failure.
299 .Pp
300 .Fn BIO_new_accept
301 returns a
302 .Vt BIO
303 or
304 .Dv NULL
305 on error.
306 .Sh EXAMPLES
307 This example accepts two connections on port 4444,
308 sends messages down each and finally closes both down.
309 .Bd -literal -offset 2n
310 BIO *abio, *cbio, *cbio2;
311 ERR_load_crypto_strings();
312 abio = BIO_new_accept("4444");
314 /* First call to BIO_accept() sets up accept BIO */
315 if (BIO_do_accept(abio) <= 0) {
316 fprintf(stderr, "Error setting up accept\en");
317 ERR_print_errors_fp(stderr);
318 exit(0);
319 }
321 /* Wait for incoming connection */
322 if (BIO_do_accept(abio) <= 0) {
323 fprintf(stderr, "Error accepting connection\en");
324 ERR_print_errors_fp(stderr);
325 exit(0);
326 }
327 fprintf(stderr, "Connection 1 established\en");
329 /* Retrieve BIO for connection */
330 cbio = BIO_pop(abio);
332 BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\en");
333 fprintf(stderr, "Sent out data on connection 1\en");
335 /* Wait for another connection */
336 if (BIO_do_accept(abio) <= 0) {
337 fprintf(stderr, "Error accepting connection\en");
338 ERR_print_errors_fp(stderr);
339 exit(0);
340 }
341 fprintf(stderr, "Connection 2 established\en");
343 /* Close accept BIO to refuse further connections */
344 cbio2 = BIO_pop(abio);
345 BIO_free(abio);
347 BIO_puts(cbio2, "Connection 2: Sending out Data on second\en");
348 fprintf(stderr, "Sent out data on connection 2\en");
349 BIO_puts(cbio, "Connection 1: Second connection established\en");
351 /* Close the two established connections */
352 BIO_free(cbio);
353 BIO_free(cbio2);
354 .Ed
355 .Sh SEE ALSO
356 .Xr BIO_new 3