mirror of
https://github.com/openssl/openssl.git
synced 2024-12-21 06:09:35 +08:00
255 lines
9.4 KiB
Plaintext
255 lines
9.4 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name,
|
|
BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_tfo_accept, BIO_set_accept_bios,
|
|
BIO_get_peer_name, BIO_get_peer_port,
|
|
BIO_get_accept_ip_family, BIO_set_accept_ip_family,
|
|
BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/bio.h>
|
|
|
|
const BIO_METHOD *BIO_s_accept(void);
|
|
|
|
long BIO_set_accept_name(BIO *b, char *name);
|
|
char *BIO_get_accept_name(BIO *b);
|
|
|
|
long BIO_set_accept_port(BIO *b, char *port);
|
|
char *BIO_get_accept_port(BIO *b);
|
|
|
|
BIO *BIO_new_accept(char *host_port);
|
|
|
|
long BIO_set_nbio_accept(BIO *b, int n);
|
|
long BIO_set_tfo_accept(BIO *b, int n);
|
|
long BIO_set_accept_bios(BIO *b, char *bio);
|
|
|
|
char *BIO_get_peer_name(BIO *b);
|
|
char *BIO_get_peer_port(BIO *b);
|
|
long BIO_get_accept_ip_family(BIO *b);
|
|
long BIO_set_accept_ip_family(BIO *b, long family);
|
|
|
|
long BIO_set_bind_mode(BIO *b, long mode);
|
|
long BIO_get_bind_mode(BIO *b);
|
|
|
|
int BIO_do_accept(BIO *b);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
BIO_s_accept() returns the accept BIO method. This is a wrapper
|
|
round the platform's TCP/IP socket accept routines.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Accept BIOs support BIO_puts() but not BIO_gets().
|
|
|
|
If the close flag is set on an accept BIO then any active
|
|
connection on that chain is shutdown and the socket closed when
|
|
the BIO is freed.
|
|
|
|
Calling BIO_reset() on an accept BIO will close any active
|
|
connection and reset the BIO into a state where it awaits another
|
|
incoming connection.
|
|
|
|
BIO_get_fd() and BIO_set_fd() can be called to retrieve or set
|
|
the accept socket. See L<BIO_s_fd(3)>
|
|
|
|
BIO_set_accept_name() uses the string B<name> to set the accept
|
|
name. The name is represented as a string of the form "host:port",
|
|
where "host" is the interface to use and "port" is the port.
|
|
The host can be "*" or empty which is interpreted as meaning
|
|
any interface. If the host is an IPv6 address, it has to be
|
|
enclosed in brackets, for example "[::1]:https". "port" has the
|
|
same syntax as the port specified in BIO_set_conn_port() for
|
|
connect BIOs, that is it can be a numerical port string or a
|
|
string to lookup using getservbyname() and a string table.
|
|
|
|
BIO_set_accept_port() uses the string B<port> to set the accept
|
|
port of BIO I<b>. "port" has the same syntax as the port specified in
|
|
BIO_set_conn_port() for connect BIOs, that is it can be a numerical
|
|
port string or a string to lookup using getservbyname() and a string
|
|
table.
|
|
If the given port is C<0> then a random available port is chosen.
|
|
It may be queried using BIO_sock_info() and L<BIO_ADDR_service_string(3)>.
|
|
|
|
BIO_new_accept() combines BIO_new() and BIO_set_accept_name() into
|
|
a single call: that is it creates a new accept BIO with port
|
|
B<host_port>.
|
|
|
|
BIO_set_nbio_accept() sets the accept socket to blocking mode
|
|
(the default) if B<n> is 0 or non blocking mode if B<n> is 1.
|
|
|
|
BIO_set_tfo_accept() enables TCP Fast Open on the accept socket
|
|
if B<n> is 1 or disables TCP Fast Open if B<n> is 0 (the default).
|
|
Setting the value to 1 is equivalent to setting B<BIO_SOCK_TFO>
|
|
in BIO_set_bind_mode().
|
|
|
|
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.
|
|
|
|
BIO_get_accept_ip_family() returns the IP family accepted by the BIO I<b>,
|
|
which may be B<BIO_FAMILY_IPV4>, B<BIO_FAMILY_IPV6>, or B<BIO_FAMILY_IPANY>.
|
|
|
|
BIO_set_accept_ip_family() sets the IP family I<family> accepted by BIO I<b>.
|
|
The default is B<BIO_FAMILY_IPANY>.
|
|
|
|
BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve
|
|
the current bind mode. If B<BIO_BIND_NORMAL> (the default) is set
|
|
then another socket cannot be bound to the same port. If
|
|
B<BIO_BIND_REUSEADDR> is set then other sockets can bind to the
|
|
same port. If B<BIO_BIND_REUSEADDR_IF_UNUSED> is set then and
|
|
attempt is first made to use BIO_BIN_NORMAL, if this fails
|
|
and the port is not in use then a second attempt is made
|
|
using B<BIO_BIND_REUSEADDR>. If B<BIO_SOCK_TFO> is set, then
|
|
the socket will be configured to accept TCP Fast Open
|
|
connections.
|
|
|
|
BIO_do_accept() serves two functions. When it is first
|
|
called, after the accept BIO has been setup, it will attempt
|
|
to create the accept socket and bind an address to it. Second
|
|
and subsequent calls to BIO_do_accept() will await an incoming
|
|
connection, or request a retry in non blocking mode.
|
|
|
|
=head1 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 then end of a chain it passes I/O calls to the next
|
|
BIO in the chain.
|
|
|
|
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.
|
|
|
|
If any additional BIOs have been set using BIO_set_accept_bios()
|
|
then they are placed between the socket and the accept BIO,
|
|
that is the chain will be accept->otherbios->socket.
|
|
|
|
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:
|
|
|
|
connection = BIO_pop(accept);
|
|
|
|
After this call B<connection> will contain a BIO for the recently
|
|
established connection and B<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 B<accept> can
|
|
be freed using BIO_free().
|
|
|
|
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 BIO_pop() (see above)
|
|
and freeing up the accept BIO after the initial connection.
|
|
|
|
If the underlying accept socket is nonblocking and BIO_do_accept() is
|
|
called to await an incoming connection it is possible for
|
|
BIO_should_io_special() with the reason 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.
|
|
|
|
BIO_set_accept_name(), BIO_get_accept_name(), BIO_set_accept_port(),
|
|
BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(),
|
|
BIO_get_peer_name(), BIO_get_peer_port(),
|
|
BIO_get_accept_ip_family(), BIO_set_accept_ip_family(),
|
|
BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
BIO_do_accept(),
|
|
BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(),
|
|
BIO_set_accept_bios(), BIO_set_accept_ip_family(), and BIO_set_bind_mode()
|
|
return 1 for success and <=0 for failure.
|
|
|
|
BIO_get_accept_name() returns the accept name or NULL on error.
|
|
BIO_get_peer_name() returns the peer name or NULL on error.
|
|
|
|
BIO_get_accept_port() returns the accept port as a string or NULL on error.
|
|
BIO_get_peer_port() returns the peer port as a string or NULL on error.
|
|
BIO_get_accept_ip_family() returns the IP family or <=0 on error.
|
|
|
|
BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or <=0 on failure.
|
|
|
|
BIO_new_accept() returns a BIO or NULL on error.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
This example accepts two connections on port 4444, sends messages
|
|
down each and finally closes both down.
|
|
|
|
BIO *abio, *cbio, *cbio2;
|
|
|
|
/* First call to BIO_accept() sets up accept BIO */
|
|
abio = BIO_new_accept("4444");
|
|
if (BIO_do_accept(abio) <= 0) {
|
|
fprintf(stderr, "Error setting up accept\n");
|
|
ERR_print_errors_fp(stderr);
|
|
exit(1);
|
|
}
|
|
|
|
/* Wait for incoming connection */
|
|
if (BIO_do_accept(abio) <= 0) {
|
|
fprintf(stderr, "Error accepting connection\n");
|
|
ERR_print_errors_fp(stderr);
|
|
exit(1);
|
|
}
|
|
fprintf(stderr, "Connection 1 established\n");
|
|
|
|
/* Retrieve BIO for connection */
|
|
cbio = BIO_pop(abio);
|
|
BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n");
|
|
fprintf(stderr, "Sent out data on connection 1\n");
|
|
|
|
/* Wait for another connection */
|
|
if (BIO_do_accept(abio) <= 0) {
|
|
fprintf(stderr, "Error accepting connection\n");
|
|
ERR_print_errors_fp(stderr);
|
|
exit(1);
|
|
}
|
|
fprintf(stderr, "Connection 2 established\n");
|
|
|
|
/* Close accept BIO to refuse further connections */
|
|
cbio2 = BIO_pop(abio);
|
|
BIO_free(abio);
|
|
BIO_puts(cbio2, "Connection 2: Sending out Data on second\n");
|
|
fprintf(stderr, "Sent out data on connection 2\n");
|
|
|
|
BIO_puts(cbio, "Connection 1: Second connection established\n");
|
|
|
|
/* Close the two established connections */
|
|
BIO_free(cbio);
|
|
BIO_free(cbio2);
|
|
|
|
=head1 HISTORY
|
|
|
|
BIO_set_tfo_accept() was added in OpenSSL 3.1.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|