--- /dev/null
+.\" $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 .
-.\" $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.
.\" 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
.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.
-.\" $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.
.\" 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
.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.
-.\" $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.
.\" 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
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
-.\" $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.
.\" 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
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.
-.\" $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
.\" 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
.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 ,
-.\" $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>,
.\" 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
.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.
-.\" $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>.
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 ,
-# $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>
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 \
projects / openbsd / commitdiff