Minimally document PKCS7_dataInit(3).

No comment when shown around among LibreSSL devs
except "very very strange function" from beck@
and "cannot say much about it" from tb@.

If needed, this can be further polished in the tree,
review is still welcome.

4 files changed, 215 insertions, 5 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 1394012e9c..5468ba9869 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.162 2020/05/20 11:40:26 schwarze Exp $
+# $OpenBSD: Makefile,v 1.163 2020/05/24 12:37:30 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -214,6 +214,7 @@ MAN=	\
         PKCS12_parse.3 \
         PKCS12_SAFEBAG_new.3 \
         PKCS5_PBKDF2_HMAC.3 \
+        PKCS7_dataInit.3 \
         PKCS7_decrypt.3 \
         PKCS7_encrypt.3 \
         PKCS7_new.3 \
diff --git a/src/lib/libcrypto/man/PKCS7_dataInit.3 b/src/lib/libcrypto/man/PKCS7_dataInit.3
new file mode 100644
index 0000000000..53090ff960
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS7_dataInit.3
@@ -0,0 +1,207 @@
+.\" $OpenBSD: PKCS7_dataInit.3,v 1.1 2020/05/24 12:37:30 schwarze Exp $
+.\"
+.\" Copyright (c) 2020 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: May 24 2020 $
+.Dt PKCS7_DATAINIT 3
+.Os
+.Sh NAME
+.Nm PKCS7_dataInit
+.Nd construct a BIO chain for adding or retrieving content
+.Sh SYNOPSIS
+.In openssl/pkcs7.h
+.Ft BIO *
+.Fo PKCS7_dataInit
+.Fa "PKCS7 *p7"
+.Fa "BIO *indata"
+.Fc
+.Sh DESCRIPTION
+.Fn PKCS7_dataInit
+constructs a BIO chain in preparation for putting data into
+or retrieving data out of
+.Fa p7 .
+Depending on the
+.Fa contentType
+of
+.Fa p7 ,
+the created chain starts with:
+.Bl -tag -width Ds
+.It for Vt SignedData :
+one or more
+.Xr BIO_f_md 3
+message digest filters
+.It for Vt EnvelopedData :
+one
+.Xr BIO_f_cipher 3
+encryption filter
+.It for Vt SignedAndEnvelopedData :
+one or more
+.Xr BIO_f_md 3
+message digest filters followed by one
+.Xr BIO_f_cipher 3
+encryption filter
+.It for Vt DigestedData :
+one
+.Xr BIO_f_md 3
+message digest filter
+.It for arbitrary data :
+no filter BIO
+.El
+.Pp
+One additional BIO is appended to the end of the chain,
+depending on the first condition that holds in the following list:
+.Bl -tag -width Ds
+.It Fa indata
+if the
+.Fa indata
+argument is not
+.Dv NULL .
+This only makes sense while verifying a detached signature, in which case
+.Fa indata
+is expected to supply the content associated with the detached signature.
+.It Xr BIO_s_null 3
+if the
+.Fa contentType
+of
+.Fa p7
+is
+.Vt SignedData
+and it is configured to contain a detached signature.
+This only makes sense while creating the detached signature.
+.It Xr BIO_new_mem_buf 3
+when reading from a
+.Vt SignedData
+or
+.Vt DigestedData
+object.
+.Fn PKCS7_dataInit
+attaches the end of the chain to the nested content of
+.Fa p7 .
+.It Xr BIO_s_mem 3
+otherwise.
+This is the most common case while writing data to
+.Fa p7 .
+.Xr PKCS7_dataFinal 3
+can later be used to transfer the data from the memory BIO into
+.Fa p7 .
+.El
+.Ss Adding content
+Before calling
+.Fn PKCS7_dataInit
+in order to add content,
+.Xr PKCS7_new 3 ,
+.Xr PKCS7_set_type 3 ,
+and
+.Xr PKCS7_content_new 3
+are typically required to create
+.Fa p7 ,
+to choose its desired type, and to allocate the nested
+.Vt ContentInfo
+structure.
+.Pp
+After calling
+.Fn PKCS7_dataInit ,
+the desired data can be written into the returned
+.Vt BIO ,
+.Xr BIO_flush 3
+can be called on it,
+.Xr PKCS7_dataFinal 3
+can be used to transfer the processed data
+from the returned memory BIO to the
+.Fa p7
+structure, and the chain can finally be destroyed with
+.Xr BIO_free_all 3 .
+.Pp
+While
+.Fn PKCS7_dataInit
+does support the
+.Vt EnvelopedData
+and
+.Vt SignedAndEnvelopedData
+types, using it for these types is awkward and error prone because
+.Xr PKCS7_content_new 3
+does not support these two types.
+So in addition to creating
+.Fa p7
+itself and setting its type, the nested
+.Fa ContentInfo
+structure also needs to be constructed with
+.Xr PKCS7_new 3
+and
+.Xr PKCS7_set_type 3
+and manually inserted into the correct field
+of the respective sub-structure of
+.Fa p7 .
+.Ss Retrieving content
+.Fn PKCS7_dataInit
+can also be called on a fully populated object of type
+.Vt SignedData
+or
+.Vt DigestedData .
+After that,
+.Xr BIO_read 3
+can be used to retrieve data from it.
+In this use case, do not call
+.Xr PKCS7_dataFinal 3 ;
+simply proceed directly to
+.Xr BIO_free_all 3
+after reading the data.
+.Sh RETURN VALUES
+.Fn PKCS7_dataInit
+returns a BIO chain on success or
+.Dv NULL
+on failure.
+It fails if
+.Fa p7
+is
+.Dv NULL ,
+if the
+.Fa content
+field of
+.Fa p7
+is empty, if the
+.Fa contentType
+of
+.Fa p7
+is unsupported, if a cipher is required but none is configured, or
+if any required operation fails, for example due to lack of memory
+or for various other reasons.
+.Sh SEE ALSO
+.Xr BIO_new 3 ,
+.Xr BIO_read 3 ,
+.Xr PKCS7_content_new 3 ,
+.Xr PKCS7_dataFinal 3 ,
+.Xr PKCS7_new 3 ,
+.Xr PKCS7_set_type 3 ,
+.Xr PKCS7_sign 3
+.Sh HISTORY
+.Fn PKCS7_dataInit
+first appeared in SSLeay 0.8.1 and has been available since
+.Ox 2.4 .
+.Sh CAVEATS
+This function does not support
+.Vt EncryptedData .
+.Sh BUGS
+If
+.Fa p7
+is a fully populated structure containing
+.Vt EnvelopedData ,
+.Vt SignedAndEnvelopedData ,
+or arbitrary data,
+.Fn PKCS7_dataInit
+returns a BIO chain that ultimately reads from an empty memory BIO,
+so reading from it will instantly return an end-of-file indication
+rather than reading the actual data contained in
+.Fa p7 .
diff --git a/src/lib/libcrypto/man/PKCS7_new.3 b/src/lib/libcrypto/man/PKCS7_new.3
index 56a8b566ba..c0943e021a 100644
--- a/src/lib/libcrypto/man/PKCS7_new.3
+++ b/src/lib/libcrypto/man/PKCS7_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PKCS7_new.3,v 1.8 2020/05/20 11:40:26 schwarze Exp $
+.\" $OpenBSD: PKCS7_new.3,v 1.9 2020/05/24 12:37:30 schwarze Exp $
 .\"
 .\" Copyright (c) 2016 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: May 20 2020 $
+.Dd $Mdocdate: May 24 2020 $
 .Dt PKCS7_NEW 3
 .Os
 .Sh NAME
@@ -246,6 +246,7 @@ frees
 .Xr i2d_PKCS7_bio_stream 3 ,
 .Xr PEM_read_PKCS7 3 ,
 .Xr PEM_write_bio_PKCS7_stream 3 ,
+.Xr PKCS7_dataInit 3 ,
 .Xr PKCS7_decrypt 3 ,
 .Xr PKCS7_encrypt 3 ,
 .Xr PKCS7_ISSUER_AND_SERIAL_digest 3 ,
diff --git a/src/lib/libcrypto/man/PKCS7_set_content.3 b/src/lib/libcrypto/man/PKCS7_set_content.3
index 1f77a8042b..fa057341d5 100644
--- a/src/lib/libcrypto/man/PKCS7_set_content.3
+++ b/src/lib/libcrypto/man/PKCS7_set_content.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PKCS7_set_content.3,v 1.1 2020/05/20 11:40:26 schwarze Exp $
+.\" $OpenBSD: PKCS7_set_content.3,v 1.2 2020/05/24 12:37:30 schwarze Exp $
 .\"
 .\" Copyright (c) 2020 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: May 20 2020 $
+.Dd $Mdocdate: May 24 2020 $
 .Dt PKCS7_SET_CONTENT 3
 .Os
 .Sh NAME
@@ -89,6 +89,7 @@ In case of failure,
 .Fa outer
 remains unchanged.
 .Sh SEE ALSO
+.Xr PKCS7_dataInit 3 ,
 .Xr PKCS7_new 3 ,
 .Xr PKCS7_set_type 3 ,
 .Xr PKCS7_sign 3