From 2080134ee98a6b23f7456c17901e7b06e4a42ed5 Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Mon, 29 Nov 2021 08:36:14 +0100 Subject: OSSL_HTTP_transfer.pod: Some clarifications on the BIO connect/disconnect callback function Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/17160) --- doc/man3/OSSL_HTTP_transfer.pod | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) (limited to 'doc') 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 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 argument, +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 refer to an I structure. -During connection establishment, just after calling BIO_do_connect_retry(), -the function is invoked with the I argument being 1 and the I +which may 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 the I argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled, else 0. On disconnect I is 0 and I 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. +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) -- cgit v1.2.3