From: schwarze <schwarze@openbsd.org>
Date: Thu, 6 Apr 2023 19:06:51 +0000 (+0000)
Subject: Properly document BIO_set_info_callback(3) and BIO_get_info_callback(3)
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=c36edd32f0d011b99b942dc8e809dfeff7ac2a99;p=openbsd

Properly document BIO_set_info_callback(3) and BIO_get_info_callback(3)
which where mentioned below SYNOPSIS and HISTORY but not described.
Also document the command constant BIO_CTRL_SET_CALLBACK
and the deprecated function type name bio_info_cb(3).
Mention that callbacks installed using BIO_set_callback_ex(3)
and BIO_set_callback(3) can tamper with *all* the return values.
---

diff --git a/lib/libcrypto/man/BIO_ctrl.3 b/lib/libcrypto/man/BIO_ctrl.3
index a5c181307e0..0c2ad2b7377 100644
--- a/lib/libcrypto/man/BIO_ctrl.3
+++ b/lib/libcrypto/man/BIO_ctrl.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_ctrl.3,v 1.17 2023/04/04 17:10:37 schwarze Exp $
+.\" $OpenBSD: BIO_ctrl.3,v 1.18 2023/04/06 19:06:51 schwarze Exp $
 .\" full merge up to: OpenSSL 24a535eaf Tue Sep 22 13:14:20 2020 +0100
 .\" selective merge up to: OpenSSL 0c5bc96f Tue Mar 15 13:57:22 2022 +0000
 .\"
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: April 4 2023 $
+.Dd $Mdocdate: April 6 2023 $
 .Dt BIO_CTRL 3
 .Os
 .Sh NAME
@@ -87,7 +87,8 @@
 .Nm BIO_ctrl_wpending ,
 .Nm BIO_get_info_callback ,
 .Nm BIO_set_info_callback ,
-.Nm BIO_info_cb
+.Nm BIO_info_cb ,
+.Nm bio_info_cb
 .Nd BIO control operations
 .Sh SYNOPSIS
 .In openssl/bio.h
@@ -179,6 +180,12 @@
 .Fa "int state"
 .Fa "int res"
 .Fc
+.Ft typedef int
+.Fo bio_info_cb
+.Fa "BIO *b"
+.Fa "int state"
+.Fa "int res"
+.Fc
 .Sh DESCRIPTION
 .Fn BIO_ctrl ,
 .Fn BIO_callback_ctrl ,
@@ -217,6 +224,12 @@ function pointer, which is built into the library for some standard BIO
 types and can be provided with
 .Xr BIO_meth_set_callback_ctrl 3
 for application-defined BIO types.
+The only
+.Fa cmd
+supported by
+.Fn BIO_callback_ctrl
+is
+.Dv BIO_CTRL_SET_CALLBACK .
 .Pp
 .Fn BIO_ptr_ctrl
 calls
@@ -299,6 +312,43 @@ and
 .Fn BIO_wpending
 are macros which call
 .Fn BIO_ctrl .
+.Pp
+.Fn BIO_set_info_callback
+installs the function pointer
+.Fa cb
+as an info callback in
+.Fa b
+by calling
+.Fn BIO_callback_ctrl
+with a command of
+.Dv BIO_CTRL_SET_CALLBACK .
+Among the BIO types built into the library, only
+.Xr BIO_s_connect 3
+and
+.Xr BIO_f_ssl 3
+support this functionality.
+Some filter BIO types forward this control call
+to the next BIO in the chain instead of processing it themselves.
+.Pp
+.Fn BIO_get_info_callback
+places the function pointer to the info callback into
+.Pf * Fa cbp
+if any was installed using
+.Fn BIO_set_info_callback
+or
+.Fn BIO_callback_ctrl .
+If the type of
+.Fa b
+supports setting an info callback but none was installed, it stores a
+.Dv NULL
+pointer in
+.Pf * Fa cbp .
+.Pp
+The function type name
+.Vt bio_info_cb
+is a deprecated synonym for
+.Vt BIO_info_cb
+provided for backward compatibility with some existing application software.
 .Sh RETURN VALUES
 The meaning of the return values of
 .Fn BIO_ctrl ,
@@ -319,11 +369,20 @@ In particular, it is returned if the
 .Fa cmd
 is unsupported by the type of
 .Fa b .
-If a callback was installed with
-.Xr BIO_set_callback_ex 3
-or
-.Xr BIO_set_callback 3
-and returns a negative value, that value is returned.
+.Pp
+.Fn BIO_callback_ctrl
+and
+.Fn BIO_set_info_callback
+return 1 on success, 0 if
+.Fa b
+is
+.Dv NULL
+or to indicate failure of a valid
+.Fa cmd ,
+or \-2 if the
+.Fa cmd
+is not supported by
+.Fa b .
 .Pp
 .Fn BIO_ptr_ctrl
 returns
@@ -373,6 +432,26 @@ or
 and
 .Fn BIO_ctrl_wpending
 return the amount of pending data.
+.Pp
+.Fn BIO_get_info_callback
+returns 1 on success, including when the type of
+.Fa b
+supports an info callback but none is installed,
+0 if
+.Fa b
+is
+.Dv NULL
+or \-2 if the type of
+.Fa b
+does not support an info callback.
+.Pp
+If a callback was installed in
+.Fa b
+using
+.Xr BIO_set_callback_ex 3
+or
+.Xr BIO_set_callback 3 ,
+it can modify the return values of all these functions.
 .Sh NOTES
 Because it can write data,
 .Fn BIO_flush
@@ -448,6 +527,15 @@ These functions have been available since
 .Fn BIO_callback_ctrl
 first appeared in OpenSSL 0.9.5 and has been available since
 .Ox 2.7 .
+.Pp
+.Fn bio_info_cb
+first appeared with a more complicated prototype in OpenSSL 0.9.6
+and has been available since
+.Ox 2.9 .
+.Pp
+.Fn BIO_info_cb
+first appeared in OpenSSL 1.1.0h and has been available since
+.Ox 6.3 .
 .Sh BUGS
 Some of the return values are ambiguous and care should be taken.
 In particular a return value of 0 can be returned if an operation