1.\" $OpenBSD: BIO_s_connect.3,v 1.14 2022/12/18 19:35:36 schwarze Exp $ 2.\" full merge up to: OpenSSL 0e474b8b Nov 1 15:45:49 2015 +0100 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2000, 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 18 2022 $ 52.Dt BIO_S_CONNECT 3 53.Os 54.Sh NAME 55.Nm BIO_s_connect , 56.Nm BIO_new_connect , 57.Nm BIO_set_conn_hostname , 58.Nm BIO_set_conn_port , 59.Nm BIO_set_conn_ip , 60.Nm BIO_set_conn_int_port , 61.Nm BIO_get_conn_hostname , 62.Nm BIO_get_conn_port , 63.Nm BIO_get_conn_ip , 64.Nm BIO_get_conn_int_port , 65.Nm BIO_set_nbio , 66.Nm BIO_do_connect 67.Nd connect BIO 68.Sh SYNOPSIS 69.In openssl/bio.h 70.Ft const BIO_METHOD * 71.Fo BIO_s_connect 72.Fa void 73.Fc 74.Ft BIO * 75.Fo BIO_new_connect 76.Fa "const char *name" 77.Fc 78.Ft long 79.Fo BIO_set_conn_hostname 80.Fa "BIO *b" 81.Fa "char *name" 82.Fc 83.Ft long 84.Fo BIO_set_conn_port 85.Fa "BIO *b" 86.Fa "char *port" 87.Fc 88.Ft long 89.Fo BIO_set_conn_ip 90.Fa "BIO *b" 91.Fa "char *ip" 92.Fc 93.Ft long 94.Fo BIO_set_conn_int_port 95.Fa "BIO *b" 96.Fa "char *port" 97.Fc 98.Ft char * 99.Fo BIO_get_conn_hostname 100.Fa "BIO *b" 101.Fc 102.Ft char * 103.Fo BIO_get_conn_port 104.Fa "BIO *b" 105.Fc 106.Ft char * 107.Fo BIO_get_conn_ip 108.Fa "BIO *b" 109.Fc 110.Ft long 111.Fo BIO_get_conn_int_port 112.Fa "BIO *b" 113.Fc 114.Ft long 115.Fo BIO_set_nbio 116.Fa "BIO *b" 117.Fa "long n" 118.Fc 119.Ft int 120.Fo BIO_do_connect 121.Fa "BIO *b" 122.Fc 123.Sh DESCRIPTION 124.Fn BIO_s_connect 125returns the connect BIO method. 126This is a wrapper around the platform's TCP/IP socket connection routines. 127.Pp 128Using connect BIOs, TCP/IP connections can be made and data 129transferred using only BIO routines. 130In this way any platform specific operations 131are hidden by the BIO abstraction. 132.Pp 133Read and write operations on a connect BIO will perform I/O 134on the underlying connection. 135If no connection is established and the port and hostname (see below) 136is set up properly, then a connection is established first. 137.Pp 138Connect BIOs support 139.Xr BIO_puts 3 140but not 141.Xr BIO_gets 3 . 142.Pp 143If the close flag is set on a connect BIO, then any active connection 144is shutdown and the socket closed when the BIO is freed. 145.Pp 146Calling 147.Xr BIO_reset 3 148on a connect BIO will close any active connection and reset the BIO 149into a state where it can connect to the same host again. 150.Pp 151.Xr BIO_get_fd 3 152places the underlying socket in 153.Fa c 154if it is not 155.Dv NULL 156and also returns the socket. 157If 158.Fa c 159is not 160.Dv NULL , 161it should be of type 162.Vt "int *" . 163.Pp 164.Fn BIO_set_conn_hostname 165uses the string 166.Fa name 167to set the hostname. 168The hostname can be an IP address. 169The hostname can also include the port in the form 170.Ar hostname : Ns Ar port . 171It is also acceptable to use the forms 172.Ar hostname Ns / Ns Pa any/other/path 173or 174.Ar hostname : Ns Ar port Ns / Ns Pa any/other/path . 175.Pp 176.Fn BIO_set_conn_port 177sets the port to 178.Fa port . 179.Fa port 180is looked up as a service using 181.Xr getaddrinfo 3 182.Pp 183.Fn BIO_set_conn_ip 184sets the IP address to 185.Fa ip 186using binary form i.e. four bytes specifying the IP address 187in big-endian form. 188.Pp 189.Fn BIO_set_conn_int_port 190sets the port using 191.Fa port . 192.Fa port 193should 194be of type 195.Vt "int *" . 196.Pp 197.Fn BIO_get_conn_hostname 198returns the hostname of the connect BIO or 199.Dv NULL 200if the BIO is initialized but no hostname is set. 201This return value is an internal pointer which should not be modified. 202.Pp 203.Fn BIO_get_conn_port 204returns the port as a string. 205This return value is an internal pointer which should not be modified. 206.Pp 207.Fn BIO_get_conn_ip 208returns the IP address in binary form. 209.Pp 210.Fn BIO_get_conn_int_port 211returns the port as an 212.Vt int . 213.Pp 214.Fn BIO_set_nbio 215sets the non-blocking I/O flag to 216.Fa n . 217If 218.Fa n 219is zero then blocking I/O is set. 220If 221.Fa n 222is 1 then non-blocking I/O is set. 223Blocking I/O is the default. 224The call to 225.Fn BIO_set_nbio 226should be made before the connection is established 227because non-blocking I/O is set during the connect process. 228.Pp 229.Fn BIO_new_connect 230combines 231.Xr BIO_new 3 232and 233.Fn BIO_set_conn_hostname 234into a single call. 235It creates a new connect BIO with 236.Fa name . 237.Pp 238.Fn BIO_do_connect 239attempts to connect the supplied BIO. 240It returns 1 if the connection was established successfully. 241A zero or negative value is returned if the connection 242could not be established. 243The call 244.Xr BIO_should_retry 3 245should be used for non-blocking connect BIOs 246to determine if the call should be retried. 247.Pp 248If blocking I/O is set then a non-positive return value from any 249I/O call is caused by an error condition, although a zero return 250will normally mean that the connection was closed. 251.Pp 252If the port name is supplied as part of the host name then this will 253override any value set with 254.Fn BIO_set_conn_port . 255This may be undesirable if the application does not wish to allow 256connection to arbitrary ports. 257This can be avoided by checking for the presence of the 258.Sq \&: 259character in the passed hostname and either indicating an error 260or truncating the string at that point. 261.Pp 262The values returned by 263.Fn BIO_get_conn_hostname , 264.Fn BIO_get_conn_port , 265.Fn BIO_get_conn_ip , 266and 267.Fn BIO_get_conn_int_port 268are updated when a connection attempt is made. 269Before any connection attempt the values returned 270are those set by the application itself. 271.Pp 272Applications do not have to call 273.Fn BIO_do_connect 274but may wish to do so to separate the connection process 275from other I/O processing. 276.Pp 277If non-blocking I/O is set, 278then retries will be requested as appropriate. 279.Pp 280In addition to 281.Xr BIO_should_read 3 282and 283.Xr BIO_should_write 3 284it is also possible for 285.Xr BIO_should_io_special 3 286to be true during the initial connection process with the reason 287.Dv BIO_RR_CONNECT . 288If this is returned, it is an indication 289that a connection attempt would block. 290The application should then take appropriate action to wait 291until the underlying socket has connected and retry the call. 292.Pp 293When a chain containing a connect BIO is copied with 294.Xr BIO_dup_chain 3 , 295.Fn BIO_set_conn_hostname , 296.Fn BIO_set_conn_port , 297.Fn BIO_set_nbio , 298and 299.Xr BIO_set_info_callback 3 300are called internally to automatically copy the hostname, port, 301non-blocking I/O flag, and info callback from the original BIO object 302to the new one. 303.Pp 304.Fn BIO_set_conn_hostname , 305.Fn BIO_set_conn_port , 306.Fn BIO_set_conn_ip , 307.Fn BIO_set_conn_int_port , 308.Fn BIO_get_conn_hostname , 309.Fn BIO_get_conn_port , 310.Fn BIO_get_conn_ip , 311.Fn BIO_get_conn_int_port , 312.Fn BIO_set_nbio , 313and 314.Fn BIO_do_connect 315are macros. 316.Sh RETURN VALUES 317.Fn BIO_s_connect 318returns the connect BIO method. 319.Pp 320.Xr BIO_get_fd 3 321returns the socket or -1 if the BIO has not been initialized. 322.Pp 323.Fn BIO_set_conn_hostname , 324.Fn BIO_set_conn_port , 325.Fn BIO_set_conn_ip , 326and 327.Fn BIO_set_conn_int_port 328always return 1. 329.Pp 330.Fn BIO_get_conn_hostname 331returns the connected hostname or 332.Dv NULL 333if none is set. 334.Pp 335.Fn BIO_get_conn_port 336returns a string representing the connected port or 337.Dv NULL 338if not set. 339.Pp 340.Fn BIO_get_conn_ip 341returns a pointer to the connected IP address in binary form 342or all zeros if not set. 343.Pp 344.Fn BIO_get_conn_int_port 345returns the connected port or 0 if none was set. 346.Pp 347.Fn BIO_set_nbio 348always returns 1. 349.Pp 350.Fn BIO_do_connect 351returns 1 if the connection was successfully 352established and 0 or -1 if the connection failed. 353.Sh EXAMPLES 354This example connects to a webserver on the local host and attempts 355to retrieve a page and copy the result to standard output. 356.Bd -literal -offset 2n 357BIO *cbio, *out; 358int len; 359char tmpbuf[1024]; 360 361ERR_load_crypto_strings(); 362cbio = BIO_new_connect("localhost:http"); 363out = BIO_new_fp(stdout, BIO_NOCLOSE); 364if (BIO_do_connect(cbio) <= 0) { 365 fprintf(stderr, "Error connecting to server\en"); 366 ERR_print_errors_fp(stderr); 367 /* whatever ... */ 368} 369BIO_puts(cbio, "GET / HTTP/1.0\en\en"); 370for(;;) { 371 len = BIO_read(cbio, tmpbuf, 1024); 372 if (len <= 0) 373 break; 374 BIO_write(out, tmpbuf, len); 375} 376BIO_free(cbio); 377BIO_free(out); 378.Ed 379.Sh SEE ALSO 380.Xr BIO_new 3 381.Sh HISTORY 382.Fn BIO_s_connect , 383.Fn BIO_new_connect , 384.Fn BIO_set_nbio , 385and 386.Fn BIO_do_connect 387first appeared in SSLeay 0.8.0. 388.Fn BIO_set_conn_hostname , 389.Fn BIO_set_conn_port , 390.Fn BIO_set_conn_ip , 391.Fn BIO_set_conn_int_port , 392.Fn BIO_get_conn_hostname , 393.Fn BIO_get_conn_port , 394.Fn BIO_get_conn_ip , 395and 396.Fn BIO_get_conn_int_port 397first appeared in SSLeay 0.9.0. 398All these functions have been available since 399.Ox 2.4 . 400