From 1a4d7a381382df1faa3c9029d2c6460342eed7da Mon Sep 17 00:00:00 2001 From: schwarze Date: Sun, 12 Dec 2021 17:31:18 +0000 Subject: [PATCH] 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. --- lib/libcrypto/man/BIO_f_asn1.3 | 5 +- lib/libcrypto/man/BIO_new_CMS.3 | 5 +- lib/libcrypto/man/BIO_new_NDEF.3 | 119 +++++++++++++++++++++++++++++++ lib/libcrypto/man/Makefile | 3 +- 4 files changed, 127 insertions(+), 5 deletions(-) create mode 100644 lib/libcrypto/man/BIO_new_NDEF.3 diff --git a/lib/libcrypto/man/BIO_f_asn1.3 b/lib/libcrypto/man/BIO_f_asn1.3 index 199ba5e9d09..3bf5a512049 100644 --- 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 .\" @@ -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 a7c2c1b2c36..c1c47e3ad32 100644 --- 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 . @@ -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 index 00000000000..a89832da400 --- /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 +.\" +.\" 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 91c763c8ed5..aab725a0e92 100644 --- 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 @@ -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 \ -- 2.20.1