From aa2877228f1ebf72d793c78512acf4cc17811b64 Mon Sep 17 00:00:00 2001 From: schwarze Date: Sat, 27 Nov 2021 16:18:03 +0000 Subject: [PATCH] new manual page BIO_f_asn1(3) --- lib/libcrypto/man/BIO_f_asn1.3 | 228 +++++++++++++++++++++++++++++++++ lib/libcrypto/man/BIO_new.3 | 5 +- lib/libcrypto/man/Makefile | 3 +- 3 files changed, 233 insertions(+), 3 deletions(-) create mode 100644 lib/libcrypto/man/BIO_f_asn1.3 diff --git a/lib/libcrypto/man/BIO_f_asn1.3 b/lib/libcrypto/man/BIO_f_asn1.3 new file mode 100644 index 00000000000..199ba5e9d09 --- /dev/null +++ b/lib/libcrypto/man/BIO_f_asn1.3 @@ -0,0 +1,228 @@ +.\" $OpenBSD: BIO_f_asn1.3,v 1.1 2021/11/27 16:18:03 schwarze 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: November 27 2021 $ +.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_new.3 b/lib/libcrypto/man/BIO_new.3 index e7c08c99f1a..17f5a708e8e 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.21 2021/07/10 15:56:18 schwarze Exp $ +.\" $OpenBSD: BIO_new.3,v 1.22 2021/11/27 16:18:03 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: July 10 2021 $ +.Dd $Mdocdate: November 27 2021 $ .Dt BIO_NEW 3 .Os .Sh NAME @@ -230,6 +230,7 @@ Create a memory BIO: .Sh SEE ALSO .Xr BIO_ctrl 3 , .Xr BIO_dump 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 6a0d65cb850..6d5f8d982b5 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.220 2021/11/22 16:19:54 schwarze Exp $ +# $OpenBSD: Makefile,v 1.221 2021/11/27 16:18:03 schwarze Exp $ .include @@ -35,6 +35,7 @@ MAN= \ BF_set_key.3 \ BIO_ctrl.3 \ BIO_dump.3 \ + BIO_f_asn1.3 \ BIO_f_base64.3 \ BIO_f_buffer.3 \ BIO_f_cipher.3 \ -- 2.20.1