1.\" $OpenBSD: BIO_accept.3,v 1.2 2023/04/30 13:38:48 schwarze Exp $ 2.\" 3.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: April 30 2023 $ 18.Dt BIO_ACCEPT 3 19.Os 20.Sh NAME 21.\" mentioned in OpenSSL documentation and still used internally in LibreSSL 22.Nm BIO_get_host_ip , 23.Nm BIO_get_port , 24.Nm BIO_get_accept_socket , 25.Nm BIO_accept , 26.Nm BIO_sock_error , 27.Nm BIO_sock_non_fatal_error , 28.Nm BIO_sock_should_retry , 29.\" used internally in LibreSSL and OpenSSL and not deprecated in OpenSSL 30.Nm BIO_socket_nbio , 31.\" mentioned in OpenSSL documentation and not deprecated in OpenSSL 32.Nm BIO_set_tcp_ndelay 33.\" deprecated in OpenSSL and unused anywhere, hence intentionally undocumented 34.\" .Nm BIO_gethostbyname 35.\" .Nm BIO_GHBN_CTRL_CACHE_SIZE 36.\" .Nm BIO_GHBN_CTRL_FLUSH 37.\" .Nm BIO_GHBN_CTRL_GET_ENTRY 38.\" .Nm BIO_GHBN_CTRL_HITS 39.\" .Nm BIO_GHBN_CTRL_MISSES 40.\" .Nm BIO_socket_ioctl 41.\" does almost nothing and used very rarely, hence intentionally undocumented 42.\" .Nm BIO_sock_init 43.\" .Nm BIO_sock_cleanup 44.Nd wrappers for socket operations 45.Sh SYNOPSIS 46.In openssl/bio.h 47.Ft int 48.Fo BIO_get_host_ip 49.Fa "const char *hostname" 50.Fa "unsigned char *in_addr_buffer" 51.Fc 52.Ft int 53.Fo BIO_get_port 54.Fa "const char *servname" 55.Fa "unsigned short *port" 56.Fc 57.Ft int 58.Fo BIO_get_accept_socket 59.Fa "char *host_port" 60.Fa "int bind_mode" 61.Fc 62.Ft int 63.Fo BIO_accept 64.Fa "int socket" 65.Fa "char **addr" 66.Fc 67.Ft int 68.Fn BIO_sock_error "int socket" 69.Ft int 70.Fn BIO_sock_non_fatal_error "int errnum" 71.Ft int 72.Fn BIO_sock_should_retry "int retval" 73.Ft int 74.Fn BIO_socket_nbio "int socket" "int mode" 75.Ft int 76.Fn BIO_set_tcp_ndelay "int socket" "int on" 77.Sh DESCRIPTION 78.Fn BIO_get_host_ip 79looks up one IPv4 address for the given 80.Fa hostname 81using 82.Xr getaddrinfo 3 83and writes the first returned IPv4 address into 84.Pf * Fa in_addr_buffer . 85The caller is responsible for providing a buffer that is at least 86.Fn sizeof in_addr_t 87bytes long. 88After a successful call, the caller needs to cast 89.Fa in_addr_buffer 90to 91.Pq Vt in_addr_t * . 92.Pp 93.Fn BIO_get_port 94looks up 95.Fa servname 96in the 97.Xr services 5 98database using 99.Xr getaddrinfo 3 100and stores the associated port number at the location specified by the 101.Fa port 102argument. 103.Pp 104.Fn BIO_get_accept_socket 105creates an IPv4 TCP socket and 106.Xr listen 2 Ns s 107for incoming connections. 108The string 109.Fa host_port 110is parsed. 111If it contains a colon, the substring before the colon is interpreted 112as a local hostname of the interface to 113.Xr bind 2 114to. 115If the hostname is empty, consists of a single asterisk 116.Pq Qq *:... , 117or if there is no colon, 118.Dv INADDR_ANY 119is used instead of a local hostname. 120The rest of the string 121.Fa host_port , 122or the whole string if it contains no colon, 123is treated as a service name. 124The hostname and the service name are converted to a local IP address 125and port number using 126.Xr getaddrinfo 3 . 127If 128.Fa bind_mode 129is the constant 130.Dv BIO_BIND_REUSEADDR , 131allowing local address reuse is attempted using 132.Xr setsockopt 2 133with an argument of 134.Dv SO_REUSEADDR 135before calling 136.Xr bind 2 . 137.Pp 138.Fn BIO_accept 139calls 140.Xr accept 2 141to receive one connection on the 142.Fa socket . 143When it receives a connection, it 144.Xr free 3 Ns s 145.Pf * Fa addr , 146and if it is an IPv4 connection, it allocates a new string, 147writes the peer IP address in dotted decimal form, a colon, 148and the decimal port number into the string, and stores a pointer 149to the string in 150.Pf * Fa addr . 151For other address families or if 152.Xr getnameinfo 3 153or memory allocation fails, 154.Pf * Fa addr 155is set to 156.Dv NULL 157but 158.Fn BIO_accept 159succeeds anyway. 160.Pp 161.Fn BIO_sock_error 162retrieves, clears, and returns the error status code of the 163.Fa socket 164by calling 165.Xr getsockopt 2 166with arguments 167.Dv SOL_SOCKET 168and 169.Dv SO_ERROR . 170.Pp 171.Fn BIO_sock_non_fatal_error 172determines whether the error status code 173.Fa errnum 174represents a recoverable error. 175.Pp 176.Fn BIO_sock_should_retry 177determines whether a recoverable error occurred by inspecting both 178.Xr errno 2 179and 180.Fa retval , 181which is supposed to usually be 182the return value of a previously called function like 183.Fn BIO_accept , 184.Xr BIO_read 3 , 185or 186.Xr BIO_write 3 . 187.Pp 188If 189.Fa mode 190is non-zero, 191.Fn BIO_socket_nbio 192switches the 193.Fa socket 194to non-blocking mode using 195.Xr fcntl 2 . 196If 197.Fa mode 198is 0, it switches to blocking mode. 199.Pp 200.Fn BIO_set_tcp_ndelay 201sets the 202.Dv TCP_NODELAY 203option on the 204.Fa socket 205if 206.Fa on 207is 1 or clears it if 208.Fa on 209is 0; see 210.Xr tcp 4 211for details. 212.Sh RETURN VALUES 213.Fn BIO_get_host_ip , 214.Fn BIO_get_port , 215and 216.Fn BIO_socket_nbio 217return 1 on success or 0 on failure. 218.Pp 219.Fn BIO_get_accept_socket 220returns the file descriptor of the newly created listening socket or \-1 if 221.Fa host_port 222is 223.Dv NULL , 224no service is specified, or 225.Xr getaddrinfo 3 , 226.Xr socket 2 , 227.Xr bind 2 , 228.Xr listen 2 , 229or memory allocation fails. 230.Pp 231.Fn BIO_accept 232returns the file descriptor of the received connection, 233\-1 on fatal errors, that is, when 234.Fa addr 235is 236.Dv NULL 237or 238.Xr accept 2 239fails fatally, or \-2 when 240.Xr accept 2 241fails in a non-fatal way and might succeed when retried later. 242.Pp 243.Fn BIO_sock_error 244returns an error status code like 245.Dv EAGAIN , 246.Dv ECONNABORTED , 247.Dv ECONNREFUSED , 248.Dv ECONNRESET , 249.Dv ELOOP , 250.Dv EMSGSIZE , 251.Dv ENOBUFS , 252.Dv ENOTCONN , 253.Dv EPIPE , 254.Dv ETIMEDOUT , 255or others, 0 if the 256.Fa socket 257is not in an error state, or 1 if 258.Xr getsockopt 2 259fails. 260.Pp 261.Fn BIO_sock_non_fatal_error 262returns 1 if 263.Fa errnum 264is 265.Dv EAGAIN , 266.Dv EALREADY , 267.Dv EINPROGRESS , 268.Dv EINTR , 269or 270.Dv ENOTCONN 271and 0 otherwise, even if 272.Fa errnum 273is 0. 274.Pp 275.Fn BIO_sock_should_retry 276returns 1 if 277.Fn BIO_sock_non_fatal_error errno 278is 1 and 279.Fa retval 280is either 0 or \-1, or 0 otherwise. 281.Pp 282.Fn BIO_set_tcp_ndelay 283returns 0 on success or \-1 on failure. 284.Sh ERRORS 285If 286.Fn BIO_get_host_ip , 287.Fn BIO_get_port , 288or 289.Fn BIO_get_accept_socket 290fail or 291.Fn BIO_accept 292fails fatally, the following diagnostics can be retrieved with 293.Xr ERR_get_error 3 , 294.Xr ERR_GET_REASON 3 , 295and 296.Xr ERR_reason_error_string 3 : 297.Bl -tag -width Ds 298.It Dv BIO_R_ACCEPT_ERROR Qq "accept error" 299.Xr accept 2 300failed fatally in 301.Fn BIO_accept . 302.It Dv BIO_R_BAD_HOSTNAME_LOOKUP Qq "bad hostname lookup" 303.Xr getaddrinfo 3 304failed or 305.Fa hostname 306was 307.Dv NULL 308in 309.Fn BIO_get_host_ip , 310or 311.Xr getaddrinfo 3 312failed in 313.Fn BIO_get_accept_socket . 314.It Dv BIO_R_INVALID_ARGUMENT Qq "invalid argument" 315.Xr getaddrinfo 3 316failed in 317.Fn BIO_get_port . 318.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" 319Memory allocation failed in 320.Fn BIO_get_accept_socket , 321or 322.Fn BIO_accept 323.Em succeeded 324but was unable to allocate memory for 325.Pf * Fa addr . 326For 327.Fn BIO_accept , 328the returned file descriptor is valid, 329and communication with the peer can be attempted using it. 330.It Dv BIO_R_NO_PORT_SPECIFIED Qq "no port specified" 331The 332.Fa servname 333argument was 334.Dv NULL 335in 336.Fn BIO_get_port , 337or 338.Fa host_port 339was 340.Dv NULL 341or ended after the first colon in 342.Fn BIO_get_accept_socket . 343.It Dv BIO_R_NULL_PARAMETER Qq "null parameter" 344The 345.Fa addr 346argument was 347.Dv NULL 348in 349.Fn BIO_accept . 350.It Dv BIO_R_UNABLE_TO_BIND_SOCKET Qq "unable to bind socket" 351.Xr bind 2 352failed in 353.Fn BIO_get_accept_socket . 354.It Dv BIO_R_UNABLE_TO_CREATE_SOCKET Qq "unable to create socket" 355.Xr socket 2 356failed in 357.Fn BIO_get_accept_socket . 358.It Dv BIO_R_UNABLE_TO_LISTEN_SOCKET Qq "unable to listen socket" 359.Xr listen 2 360failed in 361.Fn BIO_get_accept_socket . 362.El 363.Sh SEE ALSO 364.Xr bind 2 , 365.Xr connect 2 , 366.Xr errno 2 , 367.Xr fcntl 2 , 368.Xr getsockopt 2 , 369.Xr listen 2 , 370.Xr sigaction 2 , 371.Xr socket 2 , 372.Xr BIO_new 3 , 373.Xr BIO_read 3 , 374.Xr getaddrinfo 3 , 375.Xr ip 4 , 376.Xr tcp 4 377.Sh HISTORY 378.Fn BIO_sock_should_retry 379first appeared in SSLeay 0.6.5 and the other functions except 380.Fn BIO_socket_nbio 381in SSLeay 0.8.0. 382They have all been available since 383.Ox 2.4 . 384.Pp 385.Fn BIO_socket_nbio 386first appeared in SSLeay 0.9.1 and has been available since 387.Ox 2.6 . 388