new manual page BIO_dup_chain(3)

9 files changed, 206 insertions, 19 deletions

diff --git a/lib/libcrypto/man/BIO_dup_chain.3 b/lib/libcrypto/man/BIO_dup_chain.3
new file mode 100644
index 00000000000..561c811d5d1
--- /dev/null
+++ b/lib/libcrypto/man/BIO_dup_chain.3
@@ -0,0 +1,141 @@
+.\" $OpenBSD: BIO_dup_chain.3,v 1.1 2022/12/18 19:35:36 schwarze Exp $
+.\"
+.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: December 18 2022 $
+.Dt BIO_DUP_CHAIN 3
+.Os
+.Sh NAME
+.Nm BIO_dup_chain ,
+.Nm BIO_dup_state
+.Nd copy a BIO chain
+.Sh SYNOPSIS
+.In openssl/bio.h
+.Ft BIO *
+.Fn BIO_dup_chain "BIO *b"
+.Ft long
+.Fn BIO_dup_state "BIO *b" "BIO *new_bio"
+.Sh DESCRIPTION
+.Fn BIO_dup_chain
+copies the chain starting at
+.Fa b
+by iteratively copying
+.Fa b
+and all the BIOs following it
+and joining the copies in the same order as in the original chain.
+The copying operation is neither a deep copy nor a shallow copy.
+.Pp
+Some parts of the state of each BIO are copied,
+in particular with respect to the values returned by
+.Xr BIO_get_init 3 ,
+.Xr BIO_test_flags 3 ,
+and
+.Xr BIO_get_shutdown 3 .
+.\" XXX new_bio->num = bio->num;
+Other parts of the state of the BIOs are not copied
+but instead initialized to 0,
+in particular with respect to the values returned by
+.Xr BIO_number_read 3 ,
+.Xr BIO_number_written 3 ,
+and
+.Xr BIO_get_retry_reason 3 .
+The custom data pointer that can be used by custom BIO types
+and that can be retrieved with
+.Xr BIO_get_data 3
+is set set to
+.Dv NULL
+in the copied BIO objects rather than copied.
+The reference count of each BIO in the copied chain is set to 1.
+.Pp
+For each BIO in the chain, copying the data that was set with
+.Xr BIO_set_ex_data 3
+is attempted, which may involve calling application-defined
+callback functions.
+.Pp
+The following pointers are copied
+rather than creating deep copies of the objects pointed to:
+.Bl -bullet
+.It
+The
+.Fa type
+pointer used for creating each BIO with
+.Xr BIO_new 3 ,
+implying that functions like
+.Xr BIO_method_name 3
+return pointers to the same strings for the BIOs in the copied chain,
+and that these strings are not copied.
+.It
+All function pointers, in particular those installed with
+.Xr BIO_set_callback_ex 3
+and
+.Xr BIO_get_callback_ex 3 .
+.It
+The pointer installed with
+.Xr BIO_set_callback_arg 3 ,
+which implies that for BIOs using
+.Xr BIO_debug_callback 3 ,
+those in the copied chain use the same BIOs for debugging output
+as the corresponding ones in the original chain,
+and none of the debugging output BIOs are copied.
+.El
+.Pp
+.Fn BIO_dup_state
+is a macro that calls
+.Xr BIO_ctrl 3
+with a
+.Fa cmd
+argument of
+.Dv BIO_CTRL_DUP .
+It is automatically called for each BIO during
+.Fn BIO_dup_chain
+after the copied BIO is initialized and data copied into it,
+but before the data set with
+.Xr BIO_set_ex_data 3
+is copied into the new BIO and before it is linked into the new chain.
+.Pp
+This control operation may modify the operation of
+.Fn BIO_dup_chain
+for particular types of BIOs contained in the chain,
+for example initializing or copying additional data.
+For BIO types provided by the library, such additional effects
+are documented in the respective manual pages, in particular in
+.Xr BIO_f_buffer 3 ,
+.Xr BIO_f_cipher 3 ,
+.Xr BIO_f_md 3 ,
+.Xr BIO_f_ssl 3 ,
+.Xr BIO_s_bio 3 ,
+and
+.Xr BIO_s_connect 3 .
+.Sh RETURN VALUES
+.Fn BIO_dup_chain
+returns a pointer to the newly allocated copy of the BIO
+.Fa b
+on success or
+.Dv NULL
+on failure .
+.Pp
+.Fn BIO_dup_state
+returns 1 on success or a value less than or equal to zero on failure.
+.Sh SEE ALSO
+.Xr BIO_get_data 3 ,
+.Xr BIO_new 3 ,
+.Xr BIO_next 3 ,
+.Xr BIO_push 3
+.Sh HISTORY
+.Fn BIO_dup_chain
+and
+.Fn BIO_dup_state
+first appeared in SSLeay 0.8.0 and have been available since
+.Ox 2.4 .
diff --git a/lib/libcrypto/man/BIO_f_buffer.3 b/lib/libcrypto/man/BIO_f_buffer.3
index 27baf7270cb..a22addfbcb3 100644
--- a/lib/libcrypto/man/BIO_f_buffer.3
+++ b/lib/libcrypto/man/BIO_f_buffer.3
@@ -1,5 +1,5 @@
-.\"	$OpenBSD: BIO_f_buffer.3,v 1.11 2022/03/31 17:27:16 naddy Exp $
-.\"	OpenSSL 9b86974e Mar 19 12:32:14 2016 -0400
+.\" $OpenBSD: BIO_f_buffer.3,v 1.12 2022/12/18 19:35:36 schwarze Exp $
+.\" full merge up to OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2000, 2010, 2015, 2016 The OpenSSL Project.
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 31 2022 $
+.Dd $Mdocdate: December 18 2022 $
 .Dt BIO_F_BUFFER 3
 .Os
 .Sh NAME
@@ -159,6 +159,14 @@ such as when removing a buffering BIO using
 .Xr BIO_pop 3 .
 .Xr BIO_flush 3
 may need to be retried if the ultimate source/sink BIO is non-blocking.
+.Pp
+When a chain containing a buffering BIO is copied with
+.Xr BIO_dup_chain 3 ,
+.Fn BIO_set_read_buffer_size
+and
+.Fn BIO_set_write_buffer_size
+are called internally to automatically copy both buffer sizes from the
+original BIO object to the new one.
 .Sh RETURN VALUES
 .Fn BIO_f_buffer
 returns the buffering BIO method.
diff --git a/lib/libcrypto/man/BIO_f_cipher.3 b/lib/libcrypto/man/BIO_f_cipher.3
index 6a4e7c53eb1..794166687a3 100644
--- a/lib/libcrypto/man/BIO_f_cipher.3
+++ b/lib/libcrypto/man/BIO_f_cipher.3
@@ -1,5 +1,5 @@
-.\"	$OpenBSD: BIO_f_cipher.3,v 1.12 2019/06/06 01:06:58 schwarze Exp $
-.\"	OpenSSL 186bb907 Apr 13 11:05:13 2015 -0700
+.\" $OpenBSD: BIO_f_cipher.3,v 1.13 2022/12/18 19:35:36 schwarze Exp $
+.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2000, 2003, 2015, 2016 The OpenSSL Project.
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 6 2019 $
+.Dd $Mdocdate: December 18 2022 $
 .Dt BIO_F_CIPHER 3
 .Os
 .Sh NAME
@@ -133,6 +133,13 @@ This is useful when
 .Fn BIO_set_cipher
 is not flexible enough for the applications needs.
 .Pp
+When a chain containing a cipher BIO is copied with
+.Xr BIO_dup_chain 3 ,
+the cipher context is automatically copied from the existing BIO object
+to the new one and the init flag that can be retrieved with
+.Xr BIO_get_init 3
+is set to 1.
+.Pp
 When encrypting,
 .Xr BIO_flush 3
 must be called to flush the final block through the BIO.
diff --git a/lib/libcrypto/man/BIO_f_md.3 b/lib/libcrypto/man/BIO_f_md.3
index d1519bb0791..d98111f459c 100644
--- a/lib/libcrypto/man/BIO_f_md.3
+++ b/lib/libcrypto/man/BIO_f_md.3
@@ -1,5 +1,5 @@
-.\"	$OpenBSD: BIO_f_md.3,v 1.11 2019/06/06 01:06:58 schwarze Exp $
-.\"	OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400
+.\" $OpenBSD: BIO_f_md.3,v 1.12 2022/12/18 19:35:36 schwarze Exp $
+.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2000, 2006, 2009, 2016 The OpenSSL Project.
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 6 2019 $
+.Dd $Mdocdate: December 18 2022 $
 .Dt BIO_F_MD 3
 .Os
 .Sh NAME
@@ -145,6 +145,15 @@ is an internal context structure.
 Changes made to this context will affect the digest BIO itself, and
 the context pointer will become invalid when the digest BIO is freed.
 .Pp
+When a chain containing a message digest BIO is copied with
+.Xr BIO_dup_chain 3 ,
+.Xr EVP_MD_CTX_copy_ex 3
+is called internally to automatically copy the message digest context
+from the existing BIO object to the new one,
+and the init flag that can be retrieved with
+.Xr BIO_get_init 3
+is set to 1.
+.Pp
 After the digest has been retrieved from a digest BIO,
 it must be reinitialized by calling
 .Xr BIO_reset 3
diff --git a/lib/libcrypto/man/BIO_f_null.3 b/lib/libcrypto/man/BIO_f_null.3
index 755f37dae74..a74726e1fff 100644
--- a/lib/libcrypto/man/BIO_f_null.3
+++ b/lib/libcrypto/man/BIO_f_null.3
@@ -1,5 +1,5 @@
-.\"	$OpenBSD: BIO_f_null.3,v 1.9 2018/05/01 17:05:05 schwarze Exp $
-.\"	OpenSSL e117a890 Sep 14 12:14:41 2000 +0000
+.\" $OpenBSD: BIO_f_null.3,v 1.10 2022/12/18 19:35:36 schwarze Exp $
+.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2000 The OpenSSL Project.  All rights reserved.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: May 1 2018 $
+.Dd $Mdocdate: December 18 2022 $
 .Dt BIO_F_NULL 3
 .Os
 .Sh NAME
@@ -69,6 +69,11 @@ As may be apparent, a null filter BIO is not particularly useful.
 All requests to a null filter BIO are passed through to the next BIO
 in the chain: this means that a BIO chain containing a null filter BIO
 behaves just as though the BIO was not there.
+.Pp
+A chain containing a null filter BIO cannot be copied with
+.Xr BIO_dup_chain 3 ,
+and any attempt to do so fails and returns
+.Dv NULL .
 .Sh RETURN VALUES
 .Fn BIO_f_null
 returns the null filter BIO method.
diff --git a/lib/libcrypto/man/BIO_new.3 b/lib/libcrypto/man/BIO_new.3
index 53dee2c60aa..b4b0432d13f 100644
--- a/lib/libcrypto/man/BIO_new.3
+++ b/lib/libcrypto/man/BIO_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_new.3,v 1.23 2022/12/14 20:27:28 schwarze Exp $
+.\" $OpenBSD: BIO_new.3,v 1.24 2022/12/18 19:35:36 schwarze Exp $
 .\" full merge up to:
 .\" OpenSSL man3/BIO_new.pod fb46be03 Feb 26 11:51:31 2016 +0000
 .\" OpenSSL man7/bio.pod 631c37be Dec 12 16:56:50 2017 +0100
@@ -52,7 +52,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 14 2022 $
+.Dd $Mdocdate: December 18 2022 $
 .Dt BIO_NEW 3
 .Os
 .Sh NAME
@@ -231,6 +231,7 @@ Create a memory BIO:
 .Xr ASN1_buf_print 3 ,
 .Xr BIO_ctrl 3 ,
 .Xr BIO_dump 3 ,
+.Xr BIO_dup_chain 3 ,
 .Xr BIO_f_asn1 3 ,
 .Xr BIO_f_base64 3 ,
 .Xr BIO_f_buffer 3 ,
diff --git a/lib/libcrypto/man/BIO_s_bio.3 b/lib/libcrypto/man/BIO_s_bio.3
index bf4e8738b56..3c5b1fbe108 100644
--- a/lib/libcrypto/man/BIO_s_bio.3
+++ b/lib/libcrypto/man/BIO_s_bio.3
@@ -1,5 +1,5 @@
-.\"	$OpenBSD: BIO_s_bio.3,v 1.14 2022/03/31 17:27:16 naddy Exp $
-.\"	OpenSSL c03726ca Aug 27 12:28:08 2015 -0400
+.\" $OpenBSD: BIO_s_bio.3,v 1.15 2022/12/18 19:35:36 schwarze Exp $
+.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file was written by
 .\" Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>,
@@ -53,7 +53,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 31 2022 $
+.Dd $Mdocdate: December 18 2022 $
 .Dt BIO_S_BIO 3
 .Os
 .Sh NAME
@@ -184,6 +184,10 @@ to
 .Fa size .
 If the size is not initialized, a default value is used.
 This is currently 17K, sufficient for a maximum size TLS record.
+When a chain containing a BIO pair is copied with
+.Xr BIO_dup_chain 3 ,
+the write buffer size is automatically copied
+from the original BIO object to the new one.
 .Pp
 .Fn BIO_get_write_buf_size
 returns the size of the write buffer.
diff --git a/lib/libcrypto/man/BIO_s_connect.3 b/lib/libcrypto/man/BIO_s_connect.3
index b3f1ce87de1..ee6d4e38e1e 100644
--- a/lib/libcrypto/man/BIO_s_connect.3
+++ b/lib/libcrypto/man/BIO_s_connect.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_s_connect.3,v 1.13 2022/12/18 19:15:38 schwarze Exp $
+.\" $OpenBSD: BIO_s_connect.3,v 1.14 2022/12/18 19:35:36 schwarze Exp $
 .\" full merge up to: OpenSSL 0e474b8b Nov 1 15:45:49 2015 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -290,6 +290,17 @@ that a connection attempt would block.
 The application should then take appropriate action to wait
 until the underlying socket has connected and retry the call.
 .Pp
+When a chain containing a connect BIO is copied with
+.Xr BIO_dup_chain 3 ,
+.Fn BIO_set_conn_hostname ,
+.Fn BIO_set_conn_port ,
+.Fn BIO_set_nbio ,
+and
+.Xr BIO_set_info_callback 3
+are called internally to automatically copy the hostname, port,
+non-blocking I/O flag, and info callback from the original BIO object
+to the new one.
+.Pp
 .Fn BIO_set_conn_hostname ,
 .Fn BIO_set_conn_port ,
 .Fn BIO_set_conn_ip ,
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 12e4212215d..ea4a90e4d32 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.239 2022/12/14 20:27:28 schwarze Exp $
+# $OpenBSD: Makefile,v 1.240 2022/12/18 19:35:36 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -37,6 +37,7 @@ MAN=	\
 	BF_set_key.3 \
 	BIO_ctrl.3 \
 	BIO_dump.3 \
+	BIO_dup_chain.3 \
 	BIO_f_asn1.3 \
 	BIO_f_base64.3 \
 	BIO_f_buffer.3 \