503 lines
14 KiB
Groff
503 lines
14 KiB
Groff
.\" $OpenBSD: BIO_s_connect.3,v 1.19 2023/04/30 13:53:54 schwarze Exp $
|
|
.\" full merge up to: OpenSSL 0e474b8b Nov 1 15:45:49 2015 +0100
|
|
.\"
|
|
.\" This file is a derived work.
|
|
.\" The changes are covered by the following Copyright and license:
|
|
.\"
|
|
.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.\" The original 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: April 30 2023 $
|
|
.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 const BIO_METHOD *
|
|
.Fo BIO_s_connect
|
|
.Fa void
|
|
.Fc
|
|
.Ft BIO *
|
|
.Fo BIO_new_connect
|
|
.Fa "const 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"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_get_conn_int_port
|
|
.Fa "BIO *b"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_set_nbio
|
|
.Fa "BIO *b"
|
|
.Fa "long n"
|
|
.Fc
|
|
.Ft long
|
|
.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
|
|
.Xr BIO_set_info_callback 3
|
|
and
|
|
.Xr BIO_callback_ctrl 3
|
|
with a
|
|
.Fa cmd
|
|
of
|
|
.Dv BIO_CTRL_SET_CALLBACK
|
|
save the pointer to the
|
|
.Fa cb
|
|
function internally in
|
|
.Fa b
|
|
and
|
|
.Xr BIO_get_info_callback 3
|
|
retrieves this function pointer.
|
|
If such an info callback is installed, it is invoked whenever
|
|
a state change or error occurs in the connect BIO state machine.
|
|
The arguments of the callback include the new
|
|
.Fa state
|
|
in case of a state change or the old
|
|
.Fa state
|
|
in case of an error and the value
|
|
.Fa res
|
|
that the state machine would return to whatever operation invoked it
|
|
if no info callback had been installed.
|
|
If an info callback is installed, the state machine
|
|
returns the return value of the info callback instead.
|
|
Consequently, the info callback is supposed to usually return
|
|
.Fa res .
|
|
The precise effect of the return value depends on which operation
|
|
the state machine was invoked from.
|
|
Usually, \-1 is used to indicate failure and return values less than
|
|
or equal to zero abort the operation in question, whereas positive
|
|
values indicate success and allow the operation to proceed.
|
|
.Pp
|
|
The
|
|
.Fa state
|
|
constants passed to the callback are named according to
|
|
which operation needs to be performed next.
|
|
They are listed here in the order the states are passed through:
|
|
.Pp
|
|
.Bl -tag -width BIO_CONN_S_BLOCKED_CONNECT -offset 3n -compact
|
|
.It Dv BIO_CONN_S_BEFORE
|
|
The BIO is idle and no connection has been initiated yet.
|
|
.It Dv BIO_CONN_S_GET_IP
|
|
The hostname to connect to needs to be converted to an IP address.
|
|
.It Dv BIO_CONN_S_GET_PORT
|
|
The service name to connect to needs to be converted to a TCP port number.
|
|
.It Dv BIO_CONN_S_CREATE_SOCKET
|
|
The TCP socket needs to be created with the
|
|
.Xr socket 2
|
|
system call.
|
|
.It Dv BIO_CONN_S_NBIO
|
|
Socket options may need to be set using
|
|
.Xr fcntl 2
|
|
and
|
|
.Xr setsockopt 2 .
|
|
.It Dv BIO_CONN_S_CONNECT
|
|
The connection needs to be initiated with the
|
|
.Xr connect 2
|
|
system call.
|
|
.It Dv BIO_CONN_S_BLOCKED_CONNECT
|
|
The
|
|
.Xr connect 2
|
|
system call would have blocked and needs to be tried again.
|
|
.It Dv BIO_CONN_S_OK
|
|
The connection has been established and can now be used to transfer data.
|
|
.El
|
|
.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
|
|
When a chain containing a connect BIO is copied with
|
|
.Xr BIO_dup_chain 3 ,
|
|
.Fn BIO_set_conn_hostname ,
|
|
.Fn BIO_set_conn_port ,
|
|
.Fn BIO_set_nbio ,
|
|
and
|
|
.Xr BIO_set_info_callback 3
|
|
are called internally to automatically copy the hostname, port,
|
|
non-blocking I/O flag, and info callback from the original BIO object
|
|
to the new one.
|
|
.Pp
|
|
.Xr BIO_ctrl 3
|
|
.Fa cmd
|
|
and
|
|
.Fa larg
|
|
arguments correspond to macros as follows:
|
|
.Bl -column BIO_C_DO_STATE_MACHINE larg BIO_get_conn_hostname(3) -offset 3n
|
|
.It Fa cmd No constant Ta Fa larg Ta corresponding macro
|
|
.It Dv BIO_C_DO_STATE_MACHINE Ta 0 Ta Fn BIO_do_connect
|
|
.It Dv BIO_C_GET_CONNECT Ta 0 Ta Fn BIO_get_conn_hostname
|
|
.It Ta 1 Ta Fn BIO_get_conn_port
|
|
.It Ta 2 Ta Fn BIO_get_conn_ip
|
|
.It Ta 3 Ta Fn BIO_get_conn_int_port
|
|
.It Dv BIO_C_GET_FD Ta 0 Ta Xr BIO_get_fd 3
|
|
.It Dv BIO_C_SET_CONNECT Ta 0 Ta Fn BIO_set_conn_hostname
|
|
.It Ta 1 Ta Fn BIO_set_conn_port
|
|
.It Ta 2 Ta Fn BIO_set_conn_ip
|
|
.It Ta 3 Ta Fn BIO_set_conn_int_port
|
|
.It Dv BIO_C_SET_NBIO Ta Fa n Ta Fn BIO_set_nbio
|
|
.It Dv BIO_CTRL_GET_CLOSE Ta 0 Ta Xr BIO_get_close 3
|
|
.It Dv BIO_CTRL_RESET Ta 0 Ta Xr BIO_reset 3
|
|
.It Dv BIO_CTRL_SET_CLOSE Ta Fa flag Ta Xr BIO_set_close 3
|
|
.El
|
|
.Sh RETURN VALUES
|
|
.Fn BIO_s_connect
|
|
returns the connect BIO method.
|
|
.Pp
|
|
When called on a connect BIO object,
|
|
.Xr BIO_method_type 3
|
|
returns the constant
|
|
.Dv BIO_TYPE_CONNECT
|
|
and
|
|
.Xr BIO_method_name 3
|
|
returns a pointer to the static string
|
|
.Qq socket connect .
|
|
.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 .
|