[openssl] master update

[dev at ddvo.net]

The branch master has been updated
       via  2080134ee98a6b23f7456c17901e7b06e4a42ed5 (commit)
       via  4ee464cf8e0b8dc39970306bfbb49a6e06863e1c (commit)
      from  5fae09f3d8da7c182c6cfb6a295dcfd15ae828ae (commit)


- Log -----------------------------------------------------------------
commit 2080134ee98a6b23f7456c17901e7b06e4a42ed5
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date:   Mon Nov 29 08:36:14 2021 +0100

    OSSL_HTTP_transfer.pod: Some clarifications on the BIO connect/disconnect callback function
    
    Reviewed-by: Paul Dale <pauli at openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/17160)

commit 4ee464cf8e0b8dc39970306bfbb49a6e06863e1c
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date:   Mon Nov 22 11:29:25 2021 +0100

    OSSL_HTTP_transfer.pod: Fix omission documenting the 'ok' parameter of OSSL_HTTP_close()
    
    Reviewed-by: Paul Dale <pauli at openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/17160)

-----------------------------------------------------------------------

Summary of changes:
 doc/man3/OSSL_HTTP_transfer.pod | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod
index ff29c79837..2aef3a5347 100644
--- a/doc/man3/OSSL_HTTP_transfer.pod
+++ b/doc/man3/OSSL_HTTP_transfer.pod
@@ -95,16 +95,19 @@ I<bio_update_fn> is a BIO connect/disconnect callback function with prototype
 
  BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail)
 
-The callback may modify the HTTP BIO provided in the I<bio> argument,
+The callback function may modify the BIO provided in the I<bio> argument,
 whereby it may make use of a custom defined argument I<arg>,
-which may for instance refer to an I<SSL_CTX> structure.
-During connection establishment, just after calling BIO_do_connect_retry(),
-the function is invoked with the I<connect> argument being 1 and the I<detail>
+which may for instance point to an B<SSL_CTX> structure.
+During connection establishment, just after calling BIO_do_connect_retry(), the
+callback function is invoked with the I<connect> argument being 1 and the I<detail>
 argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled, else 0.
 On disconnect I<connect> is 0 and I<detail> is 1 if no error occurred, else 0.
-For instance, on connect the function may prepend a TLS BIO to implement HTTPS;
-after disconnect it may do some diagnostic output and/or specific cleanup.
-The function should return NULL to indicate failure.
+For instance, on connect the callback may push an SSL BIO to implement HTTPS;
+after disconnect it may do some diagnostic output and pop and free the SSL BIO.
+
+The callback function must return either the potentially modified BIO I<bio>.
+or NULL to indicate failure, in which case it should not modify the BIO.
+
 Here is a simple example that supports TLS connections (but not via a proxy):
 
  BIO *http_tls_cb(BIO *hbio, void *arg, int connect, int detail)
@@ -220,6 +223,7 @@ The caller is responsible for freeing the BIO pointer obtained.
 OSSL_HTTP_close() closes the connection and releases I<rctx>.
 The I<ok> parameter is passed to any BIO update function
 given during setup as described above for OSSL_HTTP_open().
+It must be 1 if no error occurred during the HTTP transfer and 0 otherwise.
 
 =head1 NOTES