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.

5 files changed, 14 insertions, 244 deletions

diff --git a/src/lib/libcrypto/man/BIO_ctrl.3 b/src/lib/libcrypto/man/BIO_ctrl.3
index b77c69b5bd..d4515ea9ad 100644
--- a/src/lib/libcrypto/man/BIO_ctrl.3
+++ b/src/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/src/lib/libcrypto/man/BIO_f_asn1.3 b/src/lib/libcrypto/man/BIO_f_asn1.3
deleted file mode 100644
index 19aa1f1ba7..0000000000
--- a/src/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 <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: 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/src/lib/libcrypto/man/BIO_find_type.3 b/src/lib/libcrypto/man/BIO_find_type.3
index 8169ad10fc..4a9eee7832 100644
--- a/src/lib/libcrypto/man/BIO_find_type.3
+++ b/src/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/src/lib/libcrypto/man/BIO_new.3 b/src/lib/libcrypto/man/BIO_new.3
index bce804131e..f97a314826 100644
--- a/src/lib/libcrypto/man/BIO_new.3
+++ b/src/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/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 99e1af1698..669b0c1395 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/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 <bsd.own.mk>
 
@@ -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 \