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