From 591315297ec45ada0d31f057c4f6cff7f572bf3e Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Tue, 2 Jun 2020 13:02:42 +0200 Subject: [PATCH] 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 (Merged from https://github.com/openssl/openssl/pull/12017) --- CHANGES.md | 6 ++++++ doc/man3/BIO_f_ssl.pod | 15 +++++++++------ doc/man3/BIO_s_connect.pod | 13 +++++++++---- 3 files changed, 24 insertions(+), 10 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 39088d1bc7..ca60b9c2e4 100644 --- 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 6b896e2a2b..8bbbb0436d 100644 --- 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 24f1120625..d5a909dcd2 100644 --- 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. -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 -- 2.39.2