diff options
author | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2023-06-11 18:19:50 +0200 |
---|---|---|
committer | Tomas Mraz <tomas@openssl.org> | 2023-10-10 20:36:06 +0200 |
commit | 2f768882e06eb460895ec4836e405e203ed90663 (patch) | |
tree | fe61d0a34ded714dd24e5b4b2551278c69c11944 /doc | |
parent | 4a9299ac5090dc7997bd1f2cbc56e5e11c6277ff (diff) |
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)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/OSSL_CMP_CTX_new.pod | 30 | ||||
-rw-r--r-- | 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 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. |