1.\" $OpenBSD: BIO_s_accept.3,v 1.11 2018/05/12 20:12:17 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: May 12 2018 $ 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 const 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 "const 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 113returns the accept BIO method. 114This is a wrapper round the platform's TCP/IP socket 115.Xr accept 2 116routines. 117.Pp 118Using accept BIOs, TCP/IP connections can be accepted 119and data transferred using only BIO routines. 120In this way any platform specific operations 121are hidden by the BIO abstraction. 122.Pp 123Read and write operations on an accept BIO 124will perform I/O on the underlying connection. 125If no connection is established and the port (see below) is set up 126properly then the BIO waits for an incoming connection. 127.Pp 128Accept BIOs support 129.Xr BIO_puts 3 130but not 131.Xr BIO_gets 3 . 132.Pp 133If the close flag is set on an accept BIO, then any active 134connection on that chain is shut down and the socket closed when 135the BIO is freed. 136.Pp 137Calling 138.Xr BIO_reset 3 139on an accept BIO will close any active connection and reset the BIO 140into a state where it awaits another incoming connection. 141.Pp 142.Xr BIO_get_fd 3 143and 144.Xr BIO_set_fd 3 145can be called to retrieve or set the accept socket. 146See 147.Xr BIO_s_fd 3 . 148.Pp 149.Fn BIO_set_accept_port 150uses the string 151.Fa name 152to set the accept port. 153The port is represented as a string of the form 154.Ar host : Ns Ar port , 155where 156.Ar host 157is the interface to use and 158.Ar port 159is the port. 160The host can be 161.Qq * , 162which is interpreted as meaning any interface; 163.Ar port 164has the same syntax as the port specified in 165.Xr BIO_set_conn_port 3 166for connect BIOs. 167It can be a numerical port string or a string to look up using 168.Xr getservbyname 3 169and a string table. 170.Pp 171.Fn BIO_new_accept 172combines 173.Xr BIO_new 3 174and 175.Fn BIO_set_accept_port 176into a single call. 177It creates a new accept BIO with port 178.Fa host_port . 179.Pp 180.Fn BIO_set_nbio_accept 181sets the accept socket to blocking mode (the default) if 182.Fa n 183is 0 or non-blocking mode if 184.Fa n 185is 1. 186.Pp 187.Fn BIO_set_accept_bios 188can be used to set a chain of BIOs which will be duplicated 189and prepended to the chain when an incoming connection is received. 190This is useful if, for example, a buffering or SSL BIO 191is required for each connection. 192The chain of BIOs must not be freed after this call - 193they will be automatically freed when the accept BIO is freed. 194.Pp 195.Fn BIO_set_bind_mode 196and 197.Fn BIO_get_bind_mode 198set and retrieve the current bind mode. 199If 200.Dv BIO_BIND_NORMAL Pq the default 201is set, then another socket cannot be bound to the same port. 202If 203.Dv BIO_BIND_REUSEADDR 204is set, then other sockets can bind to the same port. 205If 206.Dv BIO_BIND_REUSEADDR_IF_UNUSED 207is set, then an attempt is first made to use 208.Dv BIO_BIN_NORMAL ; 209if this fails and the port is not in use, 210then a second attempt is made using 211.Dv BIO_BIND_REUSEADDR . 212.Pp 213.Fn BIO_do_accept 214serves two purposes. 215When it is first called, after the accept BIO has been set up, 216it will attempt to create the accept socket and bind an address to it. 217Second and subsequent calls to 218.Fn BIO_do_accept 219will await an incoming connection, or request a retry in non-blocking mode. 220.Sh NOTES 221When an accept BIO is at the end of a chain, it will await an 222incoming connection before processing I/O calls. 223When an accept BIO is not at then end of a chain, 224it passes I/O calls to the next BIO in the chain. 225.Pp 226When a connection is established a new socket BIO is created 227for the connection and appended to the chain. 228That is the chain is now accept->socket. 229This effectively means that attempting I/O on an initial accept 230socket will await an incoming connection then perform I/O on it. 231.Pp 232If any additional BIOs have been set using 233.Fn BIO_set_accept_bios , 234then they are placed between the socket and the accept BIO; 235that is, the chain will be accept->otherbios->socket. 236.Pp 237If a server wishes to process multiple connections (as is normally 238the case), then the accept BIO must be made available for further 239incoming connections. 240This can be done by waiting for a connection and then calling: 241.Pp 242.Dl connection = BIO_pop(accept); 243.Pp 244After this call, 245.Sy connection 246will contain a BIO for the recently established connection and 247.Sy accept 248will now be a single BIO again which can be used 249to await further incoming connections. 250If no further connections will be accepted, the 251.Sy accept 252can be freed using 253.Xr BIO_free 3 . 254.Pp 255If only a single connection will be processed, 256it is possible to perform I/O using the accept BIO itself. 257This is often undesirable however because the accept BIO 258will still accept additional incoming connections. 259This 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 263If the underlying accept socket is non-blocking and 264.Fn BIO_do_accept 265is called to await an incoming connection, it is possible for 266.Xr BIO_should_io_special 3 267with the reason 268.Dv BIO_RR_ACCEPT . 269If this happens, then it is an indication that an accept attempt 270would block: the application should take appropriate action 271to wait until the underlying socket has accepted a connection 272and 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 , 280and 281.Fn BIO_do_accept 282are 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 , 288and 289.Fn BIO_set_bind_mode 290return 1 for success or 0 or -1 for failure. 291.Pp 292.Fn BIO_get_accept_port 293returns the port as a string or 294.Dv NULL 295on error. 296.Pp 297.Fn BIO_get_bind_mode 298returns the set of BIO_BIND flags or -1 on failure. 299.Pp 300.Fn BIO_new_accept 301returns a 302.Vt BIO 303or 304.Dv NULL 305on error. 306.Sh EXAMPLES 307This example accepts two connections on port 4444, 308sends messages down each and finally closes both down. 309.Bd -literal -offset 2n 310BIO *abio, *cbio, *cbio2; 311ERR_load_crypto_strings(); 312abio = BIO_new_accept("4444"); 313 314/* First call to BIO_accept() sets up accept BIO */ 315if (BIO_do_accept(abio) <= 0) { 316 fprintf(stderr, "Error setting up accept\en"); 317 ERR_print_errors_fp(stderr); 318 exit(0); 319} 320 321/* Wait for incoming connection */ 322if (BIO_do_accept(abio) <= 0) { 323 fprintf(stderr, "Error accepting connection\en"); 324 ERR_print_errors_fp(stderr); 325 exit(0); 326} 327fprintf(stderr, "Connection 1 established\en"); 328 329/* Retrieve BIO for connection */ 330cbio = BIO_pop(abio); 331 332BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\en"); 333fprintf(stderr, "Sent out data on connection 1\en"); 334 335/* Wait for another connection */ 336if (BIO_do_accept(abio) <= 0) { 337 fprintf(stderr, "Error accepting connection\en"); 338 ERR_print_errors_fp(stderr); 339 exit(0); 340} 341fprintf(stderr, "Connection 2 established\en"); 342 343/* Close accept BIO to refuse further connections */ 344cbio2 = BIO_pop(abio); 345BIO_free(abio); 346 347BIO_puts(cbio2, "Connection 2: Sending out Data on second\en"); 348fprintf(stderr, "Sent out data on connection 2\en"); 349BIO_puts(cbio, "Connection 1: Second connection established\en"); 350 351/* Close the two established connections */ 352BIO_free(cbio); 353BIO_free(cbio2); 354.Ed 355.Sh SEE ALSO 356.Xr BIO_new 3 357.Sh HISTORY 358.Fn BIO_s_accept , 359.Fn BIO_set_accept_port , 360.Fn BIO_new_accept , 361.Fn BIO_set_accept_bios , 362and 363.Fn BIO_do_accept 364first appeared in SSLeay 0.8.0. 365.Fn BIO_set_nbio_accept 366and 367.Fn BIO_get_accept_port 368first appeared in SSLeay 0.9.0. 369All these functions have been available since 370.Ox 2.4 . 371.Pp 372.Fn BIO_set_bind_mode 373and 374.Fn BIO_get_bind_mode 375first appeared in SSLeay 0.9.1 and have been available since 376.Ox 2.6 . 377