From 53d779ef370649322aeef29842077e51953ed810 Mon Sep 17 00:00:00 2001 From: schwarze Date: Sun, 18 Dec 2022 19:35:36 +0000 Subject: [PATCH] new manual page BIO_dup_chain(3) --- lib/libcrypto/man/BIO_dup_chain.3 | 141 ++++++++++++++++++++++++++++++ lib/libcrypto/man/BIO_f_buffer.3 | 14 ++- lib/libcrypto/man/BIO_f_cipher.3 | 13 ++- lib/libcrypto/man/BIO_f_md.3 | 15 +++- lib/libcrypto/man/BIO_f_null.3 | 11 ++- lib/libcrypto/man/BIO_new.3 | 5 +- lib/libcrypto/man/BIO_s_bio.3 | 10 ++- lib/libcrypto/man/BIO_s_connect.3 | 13 ++- lib/libcrypto/man/Makefile | 3 +- 9 files changed, 206 insertions(+), 19 deletions(-) create mode 100644 lib/libcrypto/man/BIO_dup_chain.3 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 +.\" +.\" 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 . .\" 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 . .\" 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 . .\" 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 . .\" 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 , @@ -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 . @@ -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 @@ -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 \ -- 2.20.1