From 2f768882e06eb460895ec4836e405e203ed90663 Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Sun, 11 Jun 2023 18:19:50 +0200 Subject: [PATCH] OSSL_CMP_CTX_new.pod: remove overlap with OSSL_HTTP_transfer.pod; improve the latter Reviewed-by: Todd Short Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/21176) --- doc/man3/OSSL_CMP_CTX_new.pod | 30 +++++++++++------------------- doc/man3/OSSL_HTTP_transfer.pod | 8 +++++--- 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 32fbc091581..488b22de9bf 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 if set, else C. 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 provided by L, -whereby it may make use of a custom defined argument I -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 argument being 1 and the I -argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled. On -disconnect I is 0 and I 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 provided by L +as described for the I parameter of L. +The callback may make use of a custom defined argument I, +as described for the I parameter of L. +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 structure, optionally to be used by the http connect/disconnect callback function. I is not consumed, and it must therefore explicitly be freed when not needed any more. I 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. The callback should send the CMP request message it obtains via the I 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, L, L, L, L, L, -L +L, L =head1 HISTORY diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod index e0375377e66..323525c5b06 100644 --- a/doc/man3/OSSL_HTTP_transfer.pod +++ b/doc/man3/OSSL_HTTP_transfer.pod @@ -99,8 +99,8 @@ I 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 argument, -whereby it may make use of a custom defined argument I, -which may for instance point to an B structure. +whereby it may use an optional custom defined argument I, +which can for instance point to an B structure. During connection establishment, just after calling BIO_do_connect_retry(), the callback function is invoked with the I argument being 1 and I being 1 if I is nonzero (i.e., HTTPS is requested), else 0. @@ -108,7 +108,7 @@ On disconnect I is 0 and I 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. +The callback function must return either the potentially modified BIO I 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 is not consumed, +so must be freed by the caller when not needed any more. The I parameter specifies the response header maximum line length. A value <= 0 means that the B (4KiB) is used. -- 2.47.2