OSSL_HTTP_transfer.pod: Some clarifications on the BIO connect/disconnect callback function

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/17160)

1 files changed, 10 insertions, 7 deletions

diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod
index ab03bfe60b..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)