From b18b0d49279d01a0837b8ee2fabe228a9099bd82 Mon Sep 17 00:00:00 2001 From: tb Date: Wed, 26 Jul 2023 20:01:04 +0000 Subject: [PATCH] BIO_f_asn1 and the prefix/suffix API will be removed Remove their documentation and mark some associated constants as intentionally undocumented until they will be removed from public headers. --- lib/libcrypto/man/BIO_ctrl.3 | 14 +- lib/libcrypto/man/BIO_f_asn1.3 | 228 ------------------------------ lib/libcrypto/man/BIO_find_type.3 | 8 +- lib/libcrypto/man/BIO_new.3 | 5 +- lib/libcrypto/man/Makefile | 3 +- 5 files changed, 14 insertions(+), 244 deletions(-) delete mode 100644 lib/libcrypto/man/BIO_f_asn1.3 diff --git a/lib/libcrypto/man/BIO_ctrl.3 b/lib/libcrypto/man/BIO_ctrl.3 index b77c69b5bdd..d4515ea9adc 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.23 2023/05/01 07:28:11 tb Exp $ +.\" $OpenBSD: BIO_ctrl.3,v 1.24 2023/07/26 20:01:04 tb 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: May 1 2023 $ +.Dd $Mdocdate: July 26 2023 $ .Dt BIO_CTRL 3 .Os .Sh NAME @@ -430,12 +430,10 @@ They are documented in the following manual pages: .Bl -column BIO_CTRL_DGRAM_SET_RECV_TIMEOUT BIO_dgram_recv_timedout(3)\ -offset 3n .It Fa cmd No constant Ta manual page -.It Dv BIO_C_GET_EX_ARG Ta Xr BIO_f_asn1 3 -.It Dv BIO_C_GET_PREFIX Ta Xr BIO_asn1_get_prefix 3 -.It Dv BIO_C_GET_SUFFIX Ta Xr BIO_asn1_get_suffix 3 -.It Dv BIO_C_SET_EX_ARG Ta Xr BIO_f_asn1 3 -.It Dv BIO_C_SET_PREFIX Ta Xr BIO_asn1_set_prefix 3 -.It Dv BIO_C_SET_SUFFIX Ta Xr BIO_asn1_set_suffix 3 +.\" The following constants are intentionally undocumented because +.\" BIO_f_asn1 has been removed from the public API. +.\" .It Dv BIO_C_GET_EX_ARG Ta Xr BIO_f_asn1 3 +.\" .It Dv BIO_C_SET_EX_ARG Ta Xr BIO_f_asn1 3 .It Dv BIO_CTRL_DGRAM_GET_FALLBACK_MTU Ta Xr BIO_dgram_set_peer 3 .It Dv BIO_CTRL_DGRAM_GET_MTU Ta Xr BIO_dgram_set_peer 3 .It Dv BIO_CTRL_DGRAM_GET_RECV_TIMEOUT Ta Xr BIO_dgram_recv_timedout 3 diff --git a/lib/libcrypto/man/BIO_f_asn1.3 b/lib/libcrypto/man/BIO_f_asn1.3 deleted file mode 100644 index 19aa1f1ba78..00000000000 --- a/lib/libcrypto/man/BIO_f_asn1.3 +++ /dev/null @@ -1,228 +0,0 @@ -.\" $OpenBSD: BIO_f_asn1.3,v 1.3 2023/05/01 07:28:11 tb Exp $ -.\" -.\" Copyright (c) 2021 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: May 1 2023 $ -.Dt BIO_F_ASN1 3 -.Os -.Sh NAME -.Nm BIO_f_asn1 , -.Nm asn1_ps_func , -.Nm BIO_asn1_set_prefix , -.Nm BIO_asn1_get_prefix , -.Nm BIO_asn1_set_suffix , -.Nm BIO_asn1_get_suffix -.Nd BER-encoding filter BIO -.Sh SYNOPSIS -.In openssl/asn1.h -.Ft const BIO_METHOD * -.Fn BIO_f_asn1 void -.In openssl/bio.h -.Ft typedef int -.Fo asn1_ps_func -.Fa "BIO *bio" -.Fa "unsigned char **pbuf" -.Fa "int *plen" -.Fa "void *parg" -.Fc -.Ft int -.Fo BIO_asn1_set_prefix -.Fa "BIO *chain" -.Fa "asn1_ps_func *prefix" -.Fa "asn1_ps_func *prefix_free" -.Fc -.Ft int -.Fo BIO_asn1_get_prefix -.Fa "BIO *chain" -.Fa "asn1_ps_func **pprefix" -.Fa "asn1_ps_func **pprefix_free" -.Fc -.Ft int -.Fo BIO_asn1_set_suffix -.Fa "BIO *chain" -.Fa "asn1_ps_func *suffix" -.Fa "asn1_ps_func *suffix_free" -.Fc -.Ft int -.Fo BIO_asn1_get_suffix -.Fa "BIO *chain" -.Fa "asn1_ps_func **psuffix" -.Fa "asn1_ps_func **psuffix_free" -.Fc -.Sh DESCRIPTION -.Fn BIO_f_asn1 -returns the -.Qq asn1 -BIO method. -BIOs created from it with -.Xr BIO_new 3 -are filter BIOs intended to BER-encode data written to them -and pass the encoded data on to the next BIO in the chain. -Such BIOs operate as follows: -.Bl -hang -width 1n -.It Xr BIO_method_type 3 -returns -.Dv BIO_TYPE_ASN1 . -.It Xr BIO_method_name 3 -returns a pointer to the static string -.Qq asn1 . -.It Xr BIO_write 3 -writes the DER encoding of an ASN.1 OCTET STRING with the -.Fa len -content octets in -.Fa buf -to the next BIO in the chain. -.Pp -If a -.Fa prefix -function was installed with -.Fn BIO_asn1_set_prefix , -that function is called before writing the object. -It may for example produce additional output. -If it fails, writing fails. -.Pp -If a -.Fa prefix_free -function was installed as well, that function is called -after writing any output produced by -.Fa prefix -but before writing the object. -Failure of -.Fa prefix_free -is silently ignored. -.It Xr BIO_puts 3 -operates like -.Xr BIO_write 3 -but uses the -.Xr strlen 3 -of -.Fa buf -instead of a -.Fa len -argument. -.It Xr BIO_flush 3 -calls the -.Fa suffix -callback function, if any. -If that produces any output, it calls the -.Fa suffix_free -callback function, if any, silently ignoring failure. -Finally, it calls -.Xr BIO_flush 3 -on the next BIO in the chain. -It fails if no data was previously written or if the -.Fa suffix -callback, writing, or -.Xr BIO_flush 3 -on the next BIO fail. -.It Xr BIO_ctrl 3 -with a -.Fa cmd -of -.Dv BIO_C_SET_EX_ARG -stores the pointer -.Fa parg -internally such that it will be passed to the -.Fn asn1_ps_func -callback functions. -With a -.Fa cmd -of -.Dv BIO_C_GET_EX_ARG , -it retrieves that pointer, storing it in -.Pf * Fa parg . -The commands -.Dv BIO_C_SET_PREFIX , -.Dv BIO_C_GET_PREFIX , -.Dv BIO_C_SET_SUFFIX , -.Dv BIO_C_GET_SUFFIX , -and -.Dv BIO_CTRL_FLUSH -are used internally to implement -.Fn BIO_asn1_set_prefix , -.Fn BIO_asn1_get_prefix , -.Fn BIO_asn1_set_suffix , -.Fn BIO_asn1_get_suffix -and -.Xr BIO_flush 3 -and are not intended for use by application programs. -Other commands are merely forwarded to the next BIO in the chain. -.It Xo -.Xr BIO_read 3 , -.Xr BIO_gets 3 , -and -.Xr BIO_callback_ctrl 3 -.Xc -merely call the same function on the next BIO in the chain. -.El -.Pp -If the above description of a function mentions the next BIO in the -chain, that function fails if the asn1 BIO is the last BIO in the chain. -.Pp -.Fn BIO_asn1_set_prefix -and -.Fn BIO_asn1_get_prefix -install and retrieve the -.Fa prefix -and -.Fa prefix_free -callback functions in and from the first asn1 BIO in the given -.Fa chain . -Similarly, -.Fn BIO_asn1_set_suffix -and -.Fn BIO_asn1_get_suffix -install and retrieve the -.Fa suffix -and -.Fa suffix_free -callback functions. -Passing a -.Dv NULL -pointer for any of the -.Fn asn1_ps_func -arguments disables that particular callback. -.Sh RETURN VALUES -.Fn BIO_f_asn1 -always returns a pointer to a static built-in object. -.Pp -Functions of the type -.Fn asn1_ps_func -are supposed to return 1 on success or 0 on failure. -.Pp -.Fn BIO_asn1_set_prefix , -.Fn BIO_asn1_get_prefix , -.Fn BIO_asn1_set_suffix , -and -.Fn BIO_asn1_get_suffix -return 1 on success or 0 if -.Fa chain -is a -.Dv NULL -pointer or does not contain any asn1 BIO. -They may return \-2 if a BIO is encountered in the -.Fa chain -that is not properly initialized. -.Sh SEE ALSO -.Xr ASN1_put_object 3 , -.Xr BIO_ctrl 3 , -.Xr BIO_new 3 , -.Xr BIO_next 3 , -.Xr BIO_write 3 , -.Xr i2d_ASN1_OCTET_STRING 3 -.Sh HISTORY -These functions first appeared in OpenSSL 1.0.0 -and have been available since -.Ox 4.9 . diff --git a/lib/libcrypto/man/BIO_find_type.3 b/lib/libcrypto/man/BIO_find_type.3 index 8169ad10fc1..4a9eee78321 100644 --- a/lib/libcrypto/man/BIO_find_type.3 +++ b/lib/libcrypto/man/BIO_find_type.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: BIO_find_type.3,v 1.11 2023/04/11 15:35:31 schwarze Exp $ +.\" $OpenBSD: BIO_find_type.3,v 1.12 2023/07/26 20:01:04 tb Exp $ .\" full merge up to: OpenSSL 1cb7eff4 Sep 10 13:56:40 2019 +0100 .\" .\" This file is a derived work. @@ -65,7 +65,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: April 11 2023 $ +.Dd $Mdocdate: July 26 2023 $ .Dt BIO_FIND_TYPE 3 .Os .Sh NAME @@ -180,7 +180,9 @@ and set in their type constant. .Bl -column BIO_TYPE_NULL_FILTER "datagram socket" BIO_s_datagram(3) .It Fa type No constant Ta Em name No string Ta Vt BIO_METHOD -.It Dv BIO_TYPE_ASN1 Ta asn1 Ta Xr BIO_f_asn1 3 +.\" BIO_TYPE_ASN1 is intentionally undocumented because BIO_f_asn1 was +.\" removed from the public API. +.\" .It Dv BIO_TYPE_ASN1 Ta asn1 Ta Xr BIO_f_asn1 3 .It Dv BIO_TYPE_BASE64 Ta base64 encoding Ta Xr BIO_f_base64 3 .It Dv BIO_TYPE_BUFFER Ta buffer Ta Xr BIO_f_buffer 3 .It Dv BIO_TYPE_CIPHER Ta cipher Ta Xr BIO_f_cipher 3 diff --git a/lib/libcrypto/man/BIO_new.3 b/lib/libcrypto/man/BIO_new.3 index bce804131e1..f97a3148267 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.27 2023/07/21 04:50:47 tb Exp $ +.\" $OpenBSD: BIO_new.3,v 1.28 2023/07/26 20:01:04 tb 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: July 21 2023 $ +.Dd $Mdocdate: July 26 2023 $ .Dt BIO_NEW 3 .Os .Sh NAME @@ -232,7 +232,6 @@ Create a memory BIO: .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 , .Xr BIO_f_cipher 3 , diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 99e1af1698a..669b0c13953 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.256 2023/07/22 06:34:59 tb Exp $ +# $OpenBSD: Makefile,v 1.257 2023/07/26 20:01:04 tb Exp $ .include @@ -37,7 +37,6 @@ MAN= \ BIO_ctrl.3 \ BIO_dump.3 \ BIO_dup_chain.3 \ - BIO_f_asn1.3 \ BIO_f_base64.3 \ BIO_f_buffer.3 \ BIO_f_cipher.3 \ -- 2.20.1