OSSL_CMP_CTX_new.pod: remove overlap with OSSL_HTTP_transfer.pod; improve the latter

Reviewed-by: Todd Short <todd.short@me.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21176)

2 files changed, 16 insertions, 22 deletions

diff --git a/doc/man3/OSSL_CMP_CTX_new.pod b/doc/man3/OSSL_CMP_CTX_new.pod
index 32fbc09158..488b22de9b 100644
--- a/doc/man3/OSSL_CMP_CTX_new.pod
+++ b/doc/man3/OSSL_CMP_CTX_new.pod
@@ -377,22 +377,16 @@ Defaults to the environment variable C<no_proxy> if set, else C<NO_PROXY>.
 OSSL_CMP_CTX_set_http_cb() sets the optional BIO connect/disconnect callback
 function, which has the prototype
 
- typedef BIO *(*HTTP_bio_cb_t) (BIO *bio, void *ctx, int connect, int detail);
-
-The callback may modify the I<bio> provided by L<OSSL_CMP_MSG_http_perform(3)>,
-whereby it may make use of a custom defined argument I<ctx>
-stored in the OSSL_CMP_CTX by means of OSSL_CMP_CTX_set_http_cb_arg().
-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>
-argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled. On
-disconnect I<connect> is 0 and I<detail> is 1 in case 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.
-After disconnect the modified BIO will be deallocated using BIO_free_all().
-
-OSSL_CMP_CTX_set_http_cb_arg() sets an argument, respectively a pointer to
-a structure containing arguments,
+ typedef BIO *(*HTTP_bio_cb_t) (BIO *bio, void *arg, int connect, int detail);
+
+The callback may modify the I<bio> provided by L<OSSL_CMP_MSG_http_perform(3)>
+as described for the I<bio_update_fn> parameter of L<OSSL_HTTP_open(3)>.
+The callback may make use of a custom defined argument I<arg>,
+as described for the I<arg> parameter of L<OSSL_HTTP_open(3)>.
+The argument is stored in the OSSL_CMP_CTX using OSSL_CMP_CTX_set_http_cb_arg().
+
+OSSL_CMP_CTX_set_http_cb_arg() sets the argument, respectively a pointer to
+a structure containing arguments such as an B<SSL_CTX> structure,
 optionally to be used by the http connect/disconnect callback function.
 I<arg> is not consumed, and it must therefore explicitly be freed when not
 needed any more. I<arg> may be NULL to clear the entry.
@@ -407,8 +401,6 @@ which has the type
  typedef OSSL_CMP_MSG *(*OSSL_CMP_transfer_cb_t) (OSSL_CMP_CTX *ctx,
                                                   const OSSL_CMP_MSG *req);
 
-Returns 1 on success, 0 on error.
-
 Default is NULL, which implies the use of L<OSSL_CMP_MSG_http_perform(3)>.
 The callback should send the CMP request message it obtains via the I<req>
 parameter and on success return the response, else it must return NULL.
@@ -824,7 +816,7 @@ the id-it-signKeyPairTypes OID and prints info on the General Response contents:
 L<OSSL_CMP_exec_IR_ses(3)>, L<OSSL_CMP_exec_CR_ses(3)>,
 L<OSSL_CMP_exec_KUR_ses(3)>, L<OSSL_CMP_exec_GENM_ses(3)>,
 L<OSSL_CMP_exec_certreq(3)>, L<OSSL_CMP_MSG_http_perform(3)>,
-L<ERR_print_errors_cb(3)>
+L<ERR_print_errors_cb(3)>, L<OSSL_HTTP_open(3)>
 
 =head1 HISTORY
 
diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod
index e0375377e6..323525c5b0 100644
--- a/doc/man3/OSSL_HTTP_transfer.pod
+++ b/doc/man3/OSSL_HTTP_transfer.pod
@@ -99,8 +99,8 @@ 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 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 point to an B<SSL_CTX> structure.
+whereby it may use an optional custom defined argument I<arg>,
+which can 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
 I<detail> being 1 if I<use_ssl> is nonzero (i.e., HTTPS is requested), else 0.
@@ -108,7 +108,7 @@ On disconnect I<connect> is 0 and I<detail> is 1 if no error occurred, else 0.
 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>.
+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):
@@ -135,6 +135,8 @@ Here is a simple example that supports TLS connections (but not via a proxy):
  }
 
 After disconnect the modified BIO will be deallocated using BIO_free_all().
+The optional callback function argument I<arg> is not consumed,
+so must be freed by the caller when not needed any more.
 
 The I<buf_size> parameter specifies the response header maximum line length.
 A value <= 0 means that the B<OSSL_HTTP_DEFAULT_MAX_LINE_LEN> (4KiB) is used.