From aa4d426b4d3527d7e166df1a05058c9a4a0f6683 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 30 Apr 2021 00:33:56 +0200 Subject: initial/final commit --- openssl-1.1.0h/doc/crypto/BIO_s_accept.pod | 222 +++++++++++++++++++++++++++++ 1 file changed, 222 insertions(+) create mode 100644 openssl-1.1.0h/doc/crypto/BIO_s_accept.pod (limited to 'openssl-1.1.0h/doc/crypto/BIO_s_accept.pod') diff --git a/openssl-1.1.0h/doc/crypto/BIO_s_accept.pod b/openssl-1.1.0h/doc/crypto/BIO_s_accept.pod new file mode 100644 index 0000000..ce9995d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_s_accept.pod @@ -0,0 +1,222 @@ +=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_accept_bios, +BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO + +=head1 SYNOPSIS + + #include + + 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_accept_bios(BIO *b, char *bio); + + 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_set_accept_name() uses the string B 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 to set the accept +port. "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_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. + +BIO_set_nbio_accept() sets the accept socket to blocking mode +(the default) if B is 0 or non blocking mode if B is 1. + +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_set_bind_mode() and BIO_get_bind_mode() set and retrieve +the current bind mode. If B (the default) is set +then another socket cannot be bound to the same port. If +B is set then other sockets can bind to the +same port. If B 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_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 will contain a BIO for the recently +established connection and B 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 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 non-blocking 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_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(), and BIO_set_bind_mode(), return 1 for success and 0 or +-1 for failure. + +BIO_get_accept_name() returns the accept name or NULL on error. + +BIO_get_accept_port() returns the port as a string or NULL on error. + +BIO_get_bind_mode() returns the set of B flags, or -1 on failure. + +BIO_new_accept() returns a BIO or NULL on error. + +=head1 EXAMPLE + +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 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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. + +=cut -- cgit v1.2.3