New manual page providing a rudimentary description of BIO_new_NDEF(3).

The API surrounding this is so complicated and streaming is so rarely
used in practice that describing this in more detail is not a priority
right now.  The documentation of the wrapper BIO_new_CMS(3) is also
rather vague, and BIO_new_PKCS7() isn't described at all so far.

diff --git a/lib/libcrypto/man/BIO_f_asn1.3 b/lib/libcrypto/man/BIO_f_asn1.3
index 199ba5e..3bf5a51 100644 (file)
--- a/lib/libcrypto/man/BIO_f_asn1.3
+++ b/lib/libcrypto/man/BIO_f_asn1.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_f_asn1.3,v 1.1 2021/11/27 16:18:03 schwarze Exp $
+.\" $OpenBSD: BIO_f_asn1.3,v 1.2 2021/12/12 17:31:18 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 $
+.Dd $Mdocdate: December 12 2021 $
 .Dt BIO_F_ASN1 3
 .Os
 .Sh NAME
@@ -219,6 +219,7 @@ that is not properly initialized.
 .Xr ASN1_put_object 3 ,
 .Xr BIO_ctrl 3 ,
 .Xr BIO_new 3 ,
+.Xr BIO_new_NDEF 3 ,
 .Xr BIO_next 3 ,
 .Xr BIO_write 3 ,
 .Xr i2d_ASN1_OCTET_STRING 3

diff --git a/lib/libcrypto/man/BIO_new_CMS.3 b/lib/libcrypto/man/BIO_new_CMS.3
index a7c2c1b..c1c47e3 100644 (file)
--- a/lib/libcrypto/man/BIO_new_CMS.3
+++ b/lib/libcrypto/man/BIO_new_CMS.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_new_CMS.3,v 1.7 2019/11/02 15:39:46 schwarze Exp $
+.\" $OpenBSD: BIO_new_CMS.3,v 1.8 2021/12/12 17:31:18 schwarze Exp $
 .\" full merge up to: OpenSSL df75c2bfc Dec 9 01:02:36 2018 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -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: November 2 2019 $
+.Dd $Mdocdate: December 12 2021 $
 .Dt BIO_NEW_CMS 3
 .Os
 .Sh NAME
@@ -128,6 +128,7 @@ The error can be obtained from
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
 .Xr BIO_new 3 ,
+.Xr BIO_new_NDEF 3 ,
 .Xr CMS_ContentInfo_new 3 ,
 .Xr CMS_encrypt 3 ,
 .Xr CMS_sign 3

diff --git a/lib/libcrypto/man/BIO_new_NDEF.3 b/lib/libcrypto/man/BIO_new_NDEF.3
new file mode 100644 (file)
index 0000000..a89832d
--- /dev/null
+++ b/lib/libcrypto/man/BIO_new_NDEF.3
@@ -0,0 +1,119 @@
+.\" $OpenBSD: BIO_new_NDEF.3,v 1.1 2021/12/12 17:31:18 schwarze 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: December 12 2021 $
+.Dt BIO_NEW_NDEF 3
+.Os
+.Sh NAME
+.Nm BIO_new_NDEF
+.Nd generic constructor for streaming BIO chains
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft BIO *
+.Fo BIO_new_NDEF
+.Fa "BIO *out_bio"
+.Fa "ASN1_VALUE *val_in"
+.Fa "const ASN1_ITEM *it"
+.Fc
+.Sh DESCRIPTION
+.Fn BIO_new_NDEF
+is a wrapper around
+.Xr BIO_new 3
+with a BIO
+.Fa type
+of
+.Xr BIO_f_asn1 3
+that supports streaming by providing the following additional functionality.
+.Pp
+The data type
+.Fa it
+needs to support streaming.
+Of the data types built into the library, currently only
+.Vt CMS_ContentInfo
+and
+.Vt PKCS7
+support that.
+The argument
+.Fa val_in
+needs to be of that type.
+.Pp
+A structure containing the following data is saved using
+.Xr BIO_ctrl 3
+with an argument of
+.Dv BIO_C_SET_EX_ARG
+as described is
+.Xr BIO_f_asn1 3 :
+.Pp
+.Bl -bullet -compact -offset indent
+.It
+the data type
+.Fa it
+.It
+the input value
+.Fa val_in
+.It
+a pointer to the
+.Vt unsigned char *
+content buffer of
+.Fa val_in ,
+extracted using a type-specific callback function
+.It
+a pointer to the new asn1 BIO
+.It
+a pointer to the beginning of the BIO chain;
+this may be the asn1 BIO itself, or one or more filter BIOs
+may be prepended to it in a type-specific manner,
+for example digest or encoding BIOs
+.El
+.Pp
+In order to handle the output from the new asn1 BIO, the
+.Fa out_bio
+is appended to it using
+.Xr BIO_push 3 .
+The
+.Fa out_bio
+can be a single sink BIO or a BIO chain ending in a sink BIO.
+.Pp
+A built-in
+.Fa prefix
+function is installed with
+.Xr BIO_asn1_set_prefix 3
+that encodes
+.Fa val_in
+using
+.Xr ASN1_item_ndef_i2d 3 ,
+and a built-in
+.Fa suffix
+function is installed that finalizes the written structures
+in a type-specific way.
+.Sh RETURN VALUES
+.Fn BIO_new_NDEF
+returns a pointer to the beginning of the constructed BIO chain or
+.Dv NULL
+if
+.Fa it
+does not support streaming or if memory allocation fails.
+.Sh SEE ALSO
+.Xr ASN1_item_ndef_i2d 3 ,
+.Xr BIO_ctrl 3 ,
+.Xr BIO_f_asn1 3 ,
+.Xr BIO_new 3 ,
+.Xr BIO_new_CMS 3 ,
+.Xr BIO_push 3
+.Sh HISTORY
+.Fn BIO_new_NDEF
+first appeared in OpenSSL 1.0.0 and has been available since
+.Ox 4.9 .

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 91c763c..aab725a 100644 (file)
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.222 2021/12/08 21:52:29 schwarze Exp $
+# $OpenBSD: Makefile,v 1.223 2021/12/12 17:31:18 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -48,6 +48,7 @@ MAN=  \
        BIO_meth_new.3 \
        BIO_new.3 \
        BIO_new_CMS.3 \
+       BIO_new_NDEF.3 \
        BIO_printf.3 \
        BIO_push.3 \
        BIO_read.3 \