414 lines
12 KiB
Groff
414 lines
12 KiB
Groff
.\" $OpenBSD: BIO_s_accept.3,v 1.16 2023/04/29 13:06:10 schwarze Exp $
|
|
.\" full merge up to: OpenSSL c03726ca Thu Aug 27 12:28:08 2015 -0400
|
|
.\"
|
|
.\" 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, 2014, 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 29 2023 $
|
|
.Dt BIO_S_ACCEPT 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm BIO_s_accept ,
|
|
.Nm BIO_set_accept_port ,
|
|
.Nm BIO_get_accept_port ,
|
|
.Nm BIO_new_accept ,
|
|
.Nm BIO_set_nbio_accept ,
|
|
.Nm BIO_set_accept_bios ,
|
|
.Nm BIO_set_bind_mode ,
|
|
.Nm BIO_get_bind_mode ,
|
|
.Nm BIO_do_accept
|
|
.Nd accept BIO
|
|
.Sh SYNOPSIS
|
|
.In openssl/bio.h
|
|
.Ft const BIO_METHOD *
|
|
.Fo BIO_s_accept
|
|
.Fa void
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_set_accept_port
|
|
.Fa "BIO *b"
|
|
.Fa "char *name"
|
|
.Fc
|
|
.Ft char *
|
|
.Fo BIO_get_accept_port
|
|
.Fa "BIO *b"
|
|
.Fc
|
|
.Ft BIO *
|
|
.Fo BIO_new_accept
|
|
.Fa "const char *host_port"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_set_nbio_accept
|
|
.Fa "BIO *b"
|
|
.Fa "int n"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_set_accept_bios
|
|
.Fa "BIO *b"
|
|
.Fa "char *bio"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_set_bind_mode
|
|
.Fa "BIO *b"
|
|
.Fa "long mode"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_get_bind_mode
|
|
.Fa "BIO *b"
|
|
.Fa "long dummy"
|
|
.Fc
|
|
.Fd #define BIO_BIND_NORMAL 0
|
|
.Fd #define BIO_BIND_REUSEADDR_IF_UNUSED 1
|
|
.Fd #define BIO_BIND_REUSEADDR 2
|
|
.Ft long
|
|
.Fo BIO_do_accept
|
|
.Fa "BIO *b"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
.Fn BIO_s_accept
|
|
returns the accept BIO method.
|
|
This is a wrapper round the platform's TCP/IP socket
|
|
.Xr accept 2
|
|
routines.
|
|
.Pp
|
|
Using accept BIOs, TCP/IP connections can be accepted
|
|
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 an accept BIO
|
|
will perform I/O on the underlying connection.
|
|
If no connection is established and the port (see below) is set up
|
|
properly then the BIO waits for an incoming connection.
|
|
.Pp
|
|
Accept BIOs support
|
|
.Xr BIO_puts 3
|
|
but not
|
|
.Xr BIO_gets 3 .
|
|
.Pp
|
|
If the close flag is set on an accept BIO, then any active
|
|
connection on that chain is shut down and the socket closed when
|
|
the BIO is freed.
|
|
.Pp
|
|
Calling
|
|
.Xr BIO_reset 3
|
|
on an accept BIO will close any active connection and reset the BIO
|
|
into a state where it awaits another incoming connection.
|
|
.Pp
|
|
.Xr BIO_get_fd 3
|
|
and
|
|
.Xr BIO_set_fd 3
|
|
can be called to retrieve or set the accept socket.
|
|
See
|
|
.Xr BIO_s_fd 3 .
|
|
.Pp
|
|
.Fn BIO_set_accept_port
|
|
uses the string
|
|
.Fa name
|
|
to set the accept port.
|
|
The port is represented as a string of the form
|
|
.Ar host : Ns Ar port ,
|
|
where
|
|
.Ar host
|
|
is the interface to use and
|
|
.Ar port
|
|
is the port.
|
|
The host can be
|
|
.Qq * ,
|
|
which is interpreted as meaning any interface;
|
|
.Ar port
|
|
has the same syntax as the port specified in
|
|
.Xr BIO_set_conn_port 3
|
|
for connect BIOs.
|
|
It can be a numerical port string or a string to look up using
|
|
.Xr getservbyname 3
|
|
and a string table.
|
|
.Pp
|
|
.Fn BIO_new_accept
|
|
combines
|
|
.Xr BIO_new 3
|
|
and
|
|
.Fn BIO_set_accept_port
|
|
into a single call.
|
|
It creates a new accept BIO with port
|
|
.Fa host_port .
|
|
.Pp
|
|
.Fn BIO_set_nbio_accept
|
|
sets the accept socket to blocking mode (the default) if
|
|
.Fa n
|
|
is 0 or non-blocking mode if
|
|
.Fa n
|
|
is 1.
|
|
.Pp
|
|
.Fn BIO_set_accept_bios
|
|
can be used to set a chain of BIOs which will be duplicated
|
|
and prepended to the chain when an incoming connection is received.
|
|
This is useful if, for example, a buffering or SSL BIO
|
|
is required for each connection.
|
|
The chain of BIOs must not be freed after this call -
|
|
they will be automatically freed when the accept BIO is freed.
|
|
.Pp
|
|
.Fn BIO_set_bind_mode
|
|
and
|
|
.Fn BIO_get_bind_mode
|
|
set and retrieve the current bind mode.
|
|
If
|
|
.Dv BIO_BIND_NORMAL Pq the default
|
|
is set, then another socket cannot be bound to the same port.
|
|
If
|
|
.Dv BIO_BIND_REUSEADDR
|
|
is set, then other sockets can bind to the same port.
|
|
If
|
|
.Dv BIO_BIND_REUSEADDR_IF_UNUSED
|
|
is set, then an attempt is first made to use
|
|
.Dv BIO_BIN_NORMAL ;
|
|
if this fails and the port is not in use,
|
|
then a second attempt is made using
|
|
.Dv BIO_BIND_REUSEADDR .
|
|
.Pp
|
|
.Fn BIO_do_accept
|
|
serves two purposes.
|
|
When it is first called, after the accept BIO has been set up,
|
|
it will attempt to create the accept socket and bind an address to it.
|
|
Second and subsequent calls to
|
|
.Fn BIO_do_accept
|
|
will await an incoming connection, or request a retry in non-blocking mode.
|
|
.Sh NOTES
|
|
When an accept BIO is at the end of a chain, it will await an
|
|
incoming connection before processing I/O calls.
|
|
When an accept BIO is not at the end of a chain,
|
|
it passes I/O calls to the next BIO in the chain.
|
|
.Pp
|
|
When a connection is established, a new socket BIO is created
|
|
for the connection and appended to the chain.
|
|
That is the chain is now accept->socket.
|
|
This effectively means that attempting I/O on an initial accept
|
|
socket will await an incoming connection then perform I/O on it.
|
|
.Pp
|
|
If any additional BIOs have been set using
|
|
.Fn BIO_set_accept_bios ,
|
|
then they are placed between the socket and the accept BIO;
|
|
that is, the chain will be accept->otherbios->socket.
|
|
.Pp
|
|
If a server wishes to process multiple connections (as is normally
|
|
the case), then the accept BIO must be made available for further
|
|
incoming connections.
|
|
This can be done by waiting for a connection and then calling:
|
|
.Pp
|
|
.Dl connection = BIO_pop(accept);
|
|
.Pp
|
|
After this call,
|
|
.Sy connection
|
|
will contain a BIO for the recently established connection and
|
|
.Sy accept
|
|
will now be a single BIO again which can be used
|
|
to await further incoming connections.
|
|
If no further connections will be accepted, the
|
|
.Sy accept
|
|
can be freed using
|
|
.Xr BIO_free 3 .
|
|
.Pp
|
|
If only a single connection will be processed,
|
|
it is possible to perform I/O using the accept BIO itself.
|
|
This is often undesirable however because the accept BIO
|
|
will still accept additional incoming connections.
|
|
This can be resolved by using
|
|
.Xr BIO_pop 3
|
|
(see above) and freeing up the accept BIO after the initial connection.
|
|
.Pp
|
|
If the underlying accept socket is non-blocking and
|
|
.Fn BIO_do_accept
|
|
is called to await an incoming connection, it is possible for
|
|
.Xr BIO_should_io_special 3
|
|
with the reason
|
|
.Dv BIO_RR_ACCEPT .
|
|
If this happens, then it is an indication that an accept attempt
|
|
would block: the application should take appropriate action
|
|
to wait until the underlying socket has accepted a connection
|
|
and retry the call.
|
|
.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_accept_port(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_accept
|
|
.It Dv BIO_C_GET_ACCEPT Ta 0 Ta Fn BIO_get_accept_port
|
|
.It Dv BIO_C_GET_BIND_MODE Ta 0 Ta Fn BIO_get_bind_mode
|
|
.It Dv BIO_C_GET_FD Ta 0 Ta Xr BIO_get_fd 3
|
|
.It Dv BIO_C_SET_ACCEPT Ta 0 Ta Fn BIO_set_accept_port
|
|
.It Ta 1 Ta Fn BIO_set_nbio_accept
|
|
.It Ta 2 Ta Fn BIO_set_accept_bios
|
|
.It Dv BIO_C_SET_FD Ta Fa fd Ta Xr BIO_set_fd 3
|
|
.It Dv BIO_C_SET_NBIO Ta Fa n Ta Xr BIO_set_nbio 3
|
|
.It Dv BIO_C_SET_BIND_MODE Ta Fa mode Ta Fn BIO_set_bind_mode
|
|
.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
|
|
When called on an accept BIO object,
|
|
.Xr BIO_method_type 3
|
|
returns the constant
|
|
.Dv BIO_TYPE_ACCEPT
|
|
and
|
|
.Xr BIO_method_name 3
|
|
returns a pointer to the static string
|
|
.Qq socket accept .
|
|
.Pp
|
|
.Fn BIO_do_accept ,
|
|
.Fn BIO_set_accept_port ,
|
|
.Fn BIO_set_nbio_accept ,
|
|
.Fn BIO_set_accept_bios ,
|
|
and
|
|
.Fn BIO_set_bind_mode
|
|
return 1 for success or 0 or -1 for failure.
|
|
.Pp
|
|
.Fn BIO_get_accept_port
|
|
returns the port as a string or
|
|
.Dv NULL
|
|
on error.
|
|
.Pp
|
|
.Fn BIO_get_bind_mode
|
|
returns the set of BIO_BIND flags or -1 on failure.
|
|
.Pp
|
|
.Fn BIO_new_accept
|
|
returns a
|
|
.Vt BIO
|
|
or
|
|
.Dv NULL
|
|
on error.
|
|
.Sh EXAMPLES
|
|
This example accepts two connections on port 4444,
|
|
sends messages down each and finally closes both down.
|
|
.Bd -literal -offset 2n
|
|
BIO *abio, *cbio, *cbio2;
|
|
ERR_load_crypto_strings();
|
|
abio = BIO_new_accept("4444");
|
|
|
|
/* First call to BIO_accept() sets up accept BIO */
|
|
if (BIO_do_accept(abio) <= 0) {
|
|
fprintf(stderr, "Error setting up accept\en");
|
|
ERR_print_errors_fp(stderr);
|
|
exit(0);
|
|
}
|
|
|
|
/* Wait for incoming connection */
|
|
if (BIO_do_accept(abio) <= 0) {
|
|
fprintf(stderr, "Error accepting connection\en");
|
|
ERR_print_errors_fp(stderr);
|
|
exit(0);
|
|
}
|
|
fprintf(stderr, "Connection 1 established\en");
|
|
|
|
/* Retrieve BIO for connection */
|
|
cbio = BIO_pop(abio);
|
|
|
|
BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\en");
|
|
fprintf(stderr, "Sent out data on connection 1\en");
|
|
|
|
/* Wait for another connection */
|
|
if (BIO_do_accept(abio) <= 0) {
|
|
fprintf(stderr, "Error accepting connection\en");
|
|
ERR_print_errors_fp(stderr);
|
|
exit(0);
|
|
}
|
|
fprintf(stderr, "Connection 2 established\en");
|
|
|
|
/* Close accept BIO to refuse further connections */
|
|
cbio2 = BIO_pop(abio);
|
|
BIO_free(abio);
|
|
|
|
BIO_puts(cbio2, "Connection 2: Sending out Data on second\en");
|
|
fprintf(stderr, "Sent out data on connection 2\en");
|
|
BIO_puts(cbio, "Connection 1: Second connection established\en");
|
|
|
|
/* Close the two established connections */
|
|
BIO_free(cbio);
|
|
BIO_free(cbio2);
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr BIO_new 3
|
|
.Sh HISTORY
|
|
.Fn BIO_s_accept ,
|
|
.Fn BIO_set_accept_port ,
|
|
.Fn BIO_new_accept ,
|
|
.Fn BIO_set_accept_bios ,
|
|
and
|
|
.Fn BIO_do_accept
|
|
first appeared in SSLeay 0.8.0.
|
|
.Fn BIO_set_nbio_accept
|
|
and
|
|
.Fn BIO_get_accept_port
|
|
first appeared in SSLeay 0.9.0.
|
|
All these functions have been available since
|
|
.Ox 2.4 .
|
|
.Pp
|
|
.Fn BIO_set_bind_mode
|
|
and
|
|
.Fn BIO_get_bind_mode
|
|
first appeared in SSLeay 0.9.1 and have been available since
|
|
.Ox 2.6 .
|