openssl
/
openssl
mirror of https://github.com/openssl/openssl
1
0
Fork 0
Code Issues Releases Wiki Activity

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)
This commit is contained in:
Dr. David von Oheimb 2023-06-11 18:19:50 +02:00 committed by Tomas Mraz
parent 4a9299ac50
commit 2f768882e0
2 changed files with 14 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/man3/OSSL_CMP_CTX_new.pod
View File

@ -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);
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)>,
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().
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 an argument, respectively a pointer to
a structure containing arguments,
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

8
doc/man3/OSSL_HTTP_transfer.pod
View File

@ -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.