The branch openssl-3.0 has been updated
via acf1651de1ba36e79176d9df0943698ed5bcee9c (commit)
via 8df298918f8cdc527a0799d0e9bc767cb6b6a76d (commit)
via 7e424b54b7d164149a65660013bd1943592ac4e6 (commit)
from f43654438c6abd414633778dcfcd2e8f666c1794 (commit)
- Log -----------------------------------------------------------------
commit acf1651de1ba36e79176d9df0943698ed5bcee9c
Author: Dr. David von Oheimb <david.von.ohe...@siemens.com>
Date: Mon Nov 29 08:36:14 2021 +0100
OSSL_HTTP_transfer.pod: Some clarifications on the BIO connect/disconnect
callback function
Reviewed-by: Paul Dale <pa...@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/17160)
(cherry picked from commit 2080134ee98a6b23f7456c17901e7b06e4a42ed5)
commit 8df298918f8cdc527a0799d0e9bc767cb6b6a76d
Author: Dr. David von Oheimb <david.von.ohe...@siemens.com>
Date: Mon Nov 22 11:29:25 2021 +0100
OSSL_HTTP_transfer.pod: Fix omission documenting the 'ok' parameter of
OSSL_HTTP_close()
Reviewed-by: Paul Dale <pa...@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/17160)
(cherry picked from commit 4ee464cf8e0b8dc39970306bfbb49a6e06863e1c)
commit 7e424b54b7d164149a65660013bd1943592ac4e6
Author: Dr. David von Oheimb <david.von.ohe...@siemens.com>
Date: Fri Nov 19 20:38:27 2021 +0100
BIO_push.pod: fix confusing text and add details on corner cases
Reviewed-by: Paul Dale <pa...@openssl.org>
Reviewed-by: Tomas Mraz <to...@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/17086)
(cherry picked from commit 7a37fd09a8f3607ed8acf55e03479861595be069)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/BIO_push.pod | 53 ++++++++++++++++++++++++-----------------
doc/man3/OSSL_HTTP_transfer.pod | 18 ++++++++------
2 files changed, 42 insertions(+), 29 deletions(-)
diff --git a/doc/man3/BIO_push.pod b/doc/man3/BIO_push.pod
index a9a1f84b5d..84ce3f042d 100644
--- a/doc/man3/BIO_push.pod
+++ b/doc/man3/BIO_push.pod
@@ -8,22 +8,27 @@ BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a
chain
#include <openssl/bio.h>
- BIO *BIO_push(BIO *b, BIO *append);
+ BIO *BIO_push(BIO *b, BIO *next);
BIO *BIO_pop(BIO *b);
void BIO_set_next(BIO *b, BIO *next);
=head1 DESCRIPTION
-The BIO_push() function appends the BIO B<append> to B<b>, it returns
-B<b>.
+BIO_push() pushes I<b> on I<next>.
+If I<b> is NULL the function does nothing and returns I<next>.
+Otherwise it prepends I<b>, which may be a single BIO or a chain of BIOs,
+to I<next> (unless I<next> is NULL).
+It then makes a control call on I<b> and returns I<b>.
-BIO_pop() removes the BIO B<b> from a chain and returns the next BIO
-in the chain, or NULL if there is no next BIO. The removed BIO then
-becomes a single BIO with no association with the original chain,
-it can thus be freed or attached to a different chain.
+BIO_pop() removes the BIO I<b> from any chain is is part of.
+If I<b> is NULL the function does nothing and returns NULL.
+Otherwise it makes a control call on I<b> and
+returns the next BIO in the chain, or NULL if there is no next BIO.
+The removed BIO becomes a single BIO with no association with
+the original chain, it can thus be freed or be made part of a different chain.
BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed
to
-by B<next>. The new chain may include some of the same BIOs from the old chain
+by I<next>. The new chain may include some of the same BIOs from the old chain
or it may be completely different.
=head1 NOTES
@@ -33,41 +38,45 @@ joins two BIO chains whereas BIO_pop() deletes a single BIO
from a chain,
the deleted BIO does not need to be at the end of a chain.
The process of calling BIO_push() and BIO_pop() on a BIO may have additional
-consequences (a control call is made to the affected BIOs) any effects will
-be noted in the descriptions of individual BIOs.
+consequences (a control call is made to the affected BIOs).
+Any effects will be noted in the descriptions of individual BIOs.
=head1 RETURN VALUES
-BIO_push() returns the end of the chain, B<b>.
+BIO_push() returns the head of the chain,
+which usually is I<b>, or I<next> if I<b> is NULL.
-BIO_pop() returns the next BIO in the chain, or NULL if there is no next
-BIO.
+BIO_pop() returns the next BIO in the chain,
+or NULL if there is no next BIO.
=head1 EXAMPLES
-For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
-a base64 BIO and B<f> is a file BIO.
+For these examples suppose I<md1> and I<md2> are digest BIOs,
+I<b64> is a base64 BIO and I<f> is a file BIO.
If the call:
BIO_push(b64, f);
-is made then the new chain will be B<b64-f>. After making the calls
+is made then the new chain will be I<b64-f>. After making the calls
BIO_push(md2, b64);
BIO_push(md1, md2);
-the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested
-by B<md1> and B<md2>, B<base64> encoded and written to B<f>.
+the new chain is I<md1-md2-b64-f>. Data written to I<md1> will be digested
+by I<md1> and I<md2>, base64 encoded, and finally written to I<f>.
It should be noted that reading causes data to pass in the reverse
-direction, that is data is read from B<f>, B<base64> decoded and digested
-by B<md2> and B<md1>. If the call:
+direction, that is data is read from I<f>, base64 decoded,
+and digested by I<md2> and then I<md1>.
+
+The call:
BIO_pop(md2);
-The call will return B<b64> and the new chain will be B<md1-b64-f> data can
-be written to B<md1> as before.
+will return I<b64> and the new chain will be I<md1-b64-f>.
+Data can be written to and read from I<md1> as before,
+except that I<md2> will no more be applied.
=head1 SEE ALSO
diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod
index ff29c79837..2aef3a5347 100644
--- a/doc/man3/OSSL_HTTP_transfer.pod
+++ b/doc/man3/OSSL_HTTP_transfer.pod
@@ -95,16 +95,19 @@ 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 may modify the HTTP BIO provided in the I<bio> argument,
+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 refer to an I<SSL_CTX> structure.
-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>
+which may 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 the
I<detail>
argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled, else
0.
On disconnect I<connect> is 0 and I<detail> 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<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):
BIO *http_tls_cb(BIO *hbio, void *arg, int connect, int detail)
@@ -220,6 +223,7 @@ The caller is responsible for freeing the BIO pointer
obtained.
OSSL_HTTP_close() closes the connection and releases I<rctx>.
The I<ok> parameter is passed to any BIO update function
given during setup as described above for OSSL_HTTP_open().
+It must be 1 if no error occurred during the HTTP transfer and 0 otherwise.
=head1 NOTES
