Consolidate doc of BIO_do_connect() and its alias BIO_do_handshake()

Also documents that they meanwhile try all IP addresses resolved for a given domain name

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/12017)

diff --git a/CHANGES.md b/CHANGES.md
index 39088d1bc754ddd2a80c1f3eca5542ac1b6a2782..ca60b9c2e463765a97274f0e7cce0227fe44bec1 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -172,6 +172,12 @@ OpenSSL 3.0
 
    *David von Oheimb*
 
+ * BIO_do_connect and BIO_do_handshake have been extended:
+   If domain name resolution yields multiple IP addresses all of them are tried
+   after connect() failures.
+
+   *David von Oheimb*
+
  * All of the low level RSA functions have been deprecated including:
 
    RSA_new_method, RSA_size, RSA_security_bits, RSA_get0_pss_params,

diff --git a/doc/man3/BIO_f_ssl.pod b/doc/man3/BIO_f_ssl.pod
index 6b896e2a2b1b9d8d0cca842a3973e6f529a04e3d..8bbbb0436db9f913f87feb7a7e416798d51a92d0 100644 (file)
--- a/doc/man3/BIO_f_ssl.pod
+++ b/doc/man3/BIO_f_ssl.pod
@@ -96,12 +96,15 @@ chain and calling SSL_shutdown() on its internal SSL
 pointer.
 
 BIO_do_handshake() attempts to complete an SSL handshake on the
-supplied BIO and establish the SSL connection. 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 BIO_should_retry() should be used for non blocking connect BIOs
-to determine if the call should be retried. If an SSL connection has
-already been established this call has no effect.
+-supplied BIO and establish the SSL connection.
+For non-SSL BIOs the connection is done typically at TCP level.
+If domain name resolution yields multiple IP addresses all of them are tried
+after connect() failures.
+The function returns 1 if the connection was established successfully.
+A zero or negative value is returned if the connection could not be established.
+The call BIO_should_retry() should be used for non-blocking connect BIOs
+to determine if the call should be retried.
+If a connection has already been established this call has no effect.
 
 =head1 NOTES
 

diff --git a/doc/man3/BIO_s_connect.pod b/doc/man3/BIO_s_connect.pod
index 24f1120625336ee404a65f387af479d4e3366748..d5a909dcd24b2963b18dfe06f19f03f6d5521130 100644 (file)
--- a/doc/man3/BIO_s_connect.pod
+++ b/doc/man3/BIO_s_connect.pod
@@ -94,11 +94,16 @@ non blocking I/O is set during the connect process.
 BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
 a single call: that is it creates a new connect BIO with B<name>.
 
-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 BIO_should_retry() should be used for non blocking connect BIOs
+BIO_do_connect() attempts to connect the supplied BIO.
+This performs an SSL/TLS handshake as far as supported by the BIO.
+For non-SSL BIOs the connection is done typically at TCP level.
+If domain name resolution yields multiple IP addresses all of them are tried
+after connect() failures.
+The function returns 1 if the connection was established successfully.
+A zero or negative value is returned if the connection could not be established.
+The call BIO_should_retry() should be used for non blocking connect BIOs
 to determine if the call should be retried.
+If a connection has already been established this call has no effect.
 
 =head1 NOTES