path: root/lib/libcrypto/man/BIO_s_connect.3

.\"	$OpenBSD: BIO_s_connect.3,v 1.9 2018/03/27 17:35:50 schwarze Exp $
.\"	OpenSSL 186bb907 Apr 13 11:05:13 2015 -0700
.\"
.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
.\" Copyright (c) 2000, 2015 The OpenSSL Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\"    software must display the following acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\"    endorse or promote products derived from this software without
.\"    prior written permission. For written permission, please contact
.\"    openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\"    nor may "OpenSSL" appear in their names without prior written
.\"    permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\"    acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: March 27 2018 $
.Dt BIO_S_CONNECT 3
.Os
.Sh NAME
.Nm BIO_s_connect ,
.Nm BIO_new_connect ,
.Nm BIO_set_conn_hostname ,
.Nm BIO_set_conn_port ,
.Nm BIO_set_conn_ip ,
.Nm BIO_set_conn_int_port ,
.Nm BIO_get_conn_hostname ,
.Nm BIO_get_conn_port ,
.Nm BIO_get_conn_ip ,
.Nm BIO_get_conn_int_port ,
.Nm BIO_set_nbio ,
.Nm BIO_do_connect
.Nd connect BIO
.Sh SYNOPSIS
.In openssl/bio.h
.Ft BIO_METHOD *
.Fo BIO_s_connect
.Fa void
.Fc
.Ft BIO *
.Fo BIO_new_connect
.Fa "char *name"
.Fc
.Ft long
.Fo BIO_set_conn_hostname
.Fa "BIO *b"
.Fa "char *name"
.Fc
.Ft long
.Fo BIO_set_conn_port
.Fa "BIO *b"
.Fa "char *port"
.Fc
.Ft long
.Fo BIO_set_conn_ip
.Fa "BIO *b"
.Fa "char *ip"
.Fc
.Ft long
.Fo BIO_set_conn_int_port
.Fa "BIO *b"
.Fa "char *port"
.Fc
.Ft char *
.Fo BIO_get_conn_hostname
.Fa "BIO *b"
.Fc
.Ft char *
.Fo BIO_get_conn_port
.Fa "BIO *b"
.Fc
.Ft char *
.Fo BIO_get_conn_ip
.Fa "BIO *b"
.Fa "dummy"
.Fc
.Ft long
.Fo BIO_get_conn_int_port
.Fa "BIO *b"
.Fa "int port"
.Fc
.Ft long
.Fo BIO_set_nbio
.Fa "BIO *b"
.Fa "long n"
.Fc
.Ft int
.Fo BIO_do_connect
.Fa "BIO *b"
.Fc
.Sh DESCRIPTION
.Fn BIO_s_connect
returns the connect BIO method.
This is a wrapper around the platform's TCP/IP socket connection routines.
.Pp
Using connect BIOs, TCP/IP connections can be made and data
transferred using only BIO routines.
In this way any platform specific operations
are hidden by the BIO abstraction.
.Pp
Read and write operations on a connect BIO will perform I/O
on the underlying connection.
If no connection is established and the port and hostname (see below)
is set up properly, then a connection is established first.
.Pp
Connect BIOs support
.Xr BIO_puts 3
but not
.Xr BIO_gets 3 .
.Pp
If the close flag is set on a connect BIO, then any active connection
is shutdown and the socket closed when the BIO is freed.
.Pp
Calling
.Xr BIO_reset 3
on a connect BIO will close any active connection and reset the BIO
into a state where it can connect to the same host again.
.Pp
.Xr BIO_get_fd 3
places the underlying socket in
.Fa c
if it is not
.Dv NULL
and also returns the socket.
If
.Fa c
is not
.Dv NULL
it should be of type
.Vt "int *" .
.Pp
.Fn BIO_set_conn_hostname
uses the string
.Fa name
to set the hostname.
The hostname can be an IP address.
The hostname can also include the port in the form
.Ar hostname : Ns Ar port .
It is also acceptable to use the forms
.Ar hostname Ns / Ns Pa any/other/path
or
.Ar hostname : Ns Ar port Ns / Ns Pa any/other/path .
.Pp
.Fn BIO_set_conn_port
sets the port to
.Fa port .
.Fa port
is looked up as a service using
.Xr getaddrinfo 3
.Pp
.Fn BIO_set_conn_ip
sets the IP address to
.Fa ip
using binary form i.e. four bytes specifying the IP address
in big-endian form.
.Pp
.Fn BIO_set_conn_int_port
sets the port using
.Fa port .
.Fa port
should
be of type
.Vt "int *" .
.Pp
.Fn BIO_get_conn_hostname
returns the hostname of the connect BIO or
.Dv NULL
if the BIO is initialized but no hostname is set.
This return value is an internal pointer which should not be modified.
.Pp
.Fn BIO_get_conn_port
returns the port as a string.
This return value is an internal pointer which should not be modified.
.Pp
.Fn BIO_get_conn_ip
returns the IP address in binary form.
.Pp
.Fn BIO_get_conn_int_port
returns the port as an
.Vt int .
.Pp
.Fn BIO_set_nbio
sets the non-blocking I/O flag to
.Fa n .
If
.Fa n
is zero then blocking I/O is set.
If
.Fa n
is 1 then non-blocking I/O is set.
Blocking I/O is the default.
The call to
.Fn BIO_set_nbio
should be made before the connection is established
because non-blocking I/O is set during the connect process.
.Pp
.Fn BIO_new_connect
combines
.Xr BIO_new 3
and
.Fn BIO_set_conn_hostname
into a single call.
It creates a new connect BIO with
.Fa name .
.Pp
.Fn BIO_do_connect
attempts to connect the supplied BIO.
It returns 1 if the connection was established successfully.
A zero or negative value is returned if the connection
could not be established.
The call
.Xr BIO_should_retry 3
should be used for non-blocking connect BIOs
to determine if the call should be retried.
.Pp
If blocking I/O is set then a non-positive return value from any
I/O call is caused by an error condition, although a zero return
will normally mean that the connection was closed.
.Pp
If the port name is supplied as part of the host name then this will
override any value set with
.Fn BIO_set_conn_port .
This may be undesirable if the application does not wish to allow
connection to arbitrary ports.
This can be avoided by checking for the presence of the
.Sq \&:
character in the passed hostname and either indicating an error
or truncating the string at that point.
.Pp
The values returned by
.Fn BIO_get_conn_hostname ,
.Fn BIO_get_conn_port ,
.Fn BIO_get_conn_ip ,
and
.Fn BIO_get_conn_int_port
are updated when a connection attempt is made.
Before any connection attempt the values returned
are those set by the application itself.
.Pp
Applications do not have to call
.Fn BIO_do_connect
but may wish to do so to separate the connection process
from other I/O processing.
.Pp
If non-blocking I/O is set,
then retries will be requested as appropriate.
.Pp
In addition to
.Xr BIO_should_read 3
and
.Xr BIO_should_write 3
it is also possible for
.Xr BIO_should_io_special 3
to be true during the initial connection process with the reason
.Dv BIO_RR_CONNECT .
If this is returned, it is an indication
that a connection attempt would block.
The application should then take appropriate action to wait
until the underlying socket has connected and retry the call.
.Pp
.Fn BIO_set_conn_hostname ,
.Fn BIO_set_conn_port ,
.Fn BIO_set_conn_ip ,
.Fn BIO_set_conn_int_port ,
.Fn BIO_get_conn_hostname ,
.Fn BIO_get_conn_port ,
.Fn BIO_get_conn_ip ,
.Fn BIO_get_conn_int_port ,
.Fn BIO_set_nbio ,
and
.Fn BIO_do_connect
are macros.
.Sh RETURN VALUES
.Fn BIO_s_connect
returns the connect BIO method.
.Pp
.Xr BIO_get_fd 3
returns the socket or -1 if the BIO has not been initialized.
.Pp
.Fn BIO_set_conn_hostname ,
.Fn BIO_set_conn_port ,
.Fn BIO_set_conn_ip ,
and
.Fn BIO_set_conn_int_port
always return 1.
.Pp
.Fn BIO_get_conn_hostname
returns the connected hostname or
.Dv NULL
if none is set.
.Pp
.Fn BIO_get_conn_port
returns a string representing the connected port or
.Dv NULL
if not set.
.Pp
.Fn BIO_get_conn_ip
returns a pointer to the connected IP address in binary form
or all zeros if not set.
.Pp
.Fn BIO_get_conn_int_port
returns the connected port or 0 if none was set.
.Pp
.Fn BIO_set_nbio
always returns 1.
.Pp
.Fn BIO_do_connect
returns 1 if the connection was successfully
established and 0 or -1 if the connection failed.
.Sh EXAMPLES
This example connects to a webserver on the local host and attempts
to retrieve a page and copy the result to standard output.
.Bd -literal -offset 2n
BIO *cbio, *out;
int len;
char tmpbuf[1024];

ERR_load_crypto_strings();
cbio = BIO_new_connect("localhost:http");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if (BIO_do_connect(cbio) <= 0) {
	fprintf(stderr, "Error connecting to server\en");
	ERR_print_errors_fp(stderr);
	/* whatever ... */
}
BIO_puts(cbio, "GET / HTTP/1.0\en\en");
for(;;) {
	len = BIO_read(cbio, tmpbuf, 1024);
	if (len <= 0)
		break;
	BIO_write(out, tmpbuf, len);
}
BIO_free(cbio);
BIO_free(out);
.Ed
.Sh SEE ALSO
.Xr BIO_new 3
.Sh HISTORY
.Fn BIO_s_connect ,
.Fn BIO_new_connect ,
.Fn BIO_set_nbio ,
and
.Fn BIO_do_connect
first appeared in SSLeay 0.8.0.
.Fn BIO_set_conn_hostname ,
.Fn BIO_set_conn_port ,
.Fn BIO_set_conn_ip ,
.Fn BIO_set_conn_int_port ,
.Fn BIO_get_conn_hostname ,
.Fn BIO_get_conn_port ,
.Fn BIO_get_conn_ip ,
and
.Fn BIO_get_conn_int_port
first appeared in SSLeay 0.9.0.
All these functions have been available since
.Ox 2.4 .