120 lines
2.9 KiB
Groff
120 lines
2.9 KiB
Groff
.\" $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 .
|