.\" $OpenBSD: BIO_new_NDEF.3,v 1.3 2021/12/13 13:46:09 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 13 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 in
.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 ,
.Xr i2d_ASN1_bio_stream 3
.Sh HISTORY
.Fn BIO_new_NDEF
first appeared in OpenSSL 1.0.0 and has been available since
.Ox 4.9 .