document PKCS7_dataFinal(3);

tweak and OK tb@

3 files changed, 162 insertions, 3 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 5468ba9869..8af0c34d2b 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.163 2020/05/24 12:37:30 schwarze Exp $
+# $OpenBSD: Makefile,v 1.164 2020/05/27 12:00:44 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -214,6 +214,7 @@ MAN=	\
         PKCS12_parse.3 \
         PKCS12_SAFEBAG_new.3 \
         PKCS5_PBKDF2_HMAC.3 \
+        PKCS7_dataFinal.3 \
         PKCS7_dataInit.3 \
         PKCS7_decrypt.3 \
         PKCS7_encrypt.3 \
diff --git a/src/lib/libcrypto/man/PKCS7_dataFinal.3 b/src/lib/libcrypto/man/PKCS7_dataFinal.3
new file mode 100644
index 0000000000..f9cdd62f60
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS7_dataFinal.3
@@ -0,0 +1,157 @@
+.\" $OpenBSD: PKCS7_dataFinal.3,v 1.1 2020/05/27 12:00:44 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 27 2020 $
+.Dt PKCS7_DATAFINAL 3
+.Os
+.Sh NAME
+.Nm PKCS7_dataFinal
+.Nd move data from a BIO chain to a ContentInfo object
+.Sh SYNOPSIS
+.In openssl/pkcs7.h
+.Ft int
+.Fo PKCS7_dataFinal
+.Fa "PKCS7 *p7"
+.Fa "BIO *chain"
+.Fc
+.Sh DESCRIPTION
+.Fn PKCS7_dataFinal
+transfers the data from the memory BIO at the end of the given
+.Fa chain
+into the appropriate content field of
+.Fa p7
+itself or of its appropriate substructure.
+It is typically used as the final step of populating
+.Fa p7 ,
+after creating the
+.Fa chain
+with
+.Xr PKCS7_dataInit 3
+and after writing the data into it.
+.Pp
+After calling
+.Fn PKCS7_dataFinal ,
+the program can call
+.Xr BIO_free_all 3
+on the
+.Fa chain
+because such chains are not designed for reuse.
+.Pp
+Depending on the
+.Fa contentType
+of
+.Fa p7 ,
+.Fn PKCS7_dataFinal
+sets the following fields:
+.Bl -tag -width Ds
+.It for Vt SignedData No or Vt DigestedData :
+in substructures of the
+.Fa content
+field of
+.Fa p7 :
+the
+.Fa content
+field in the
+.Vt ContentInfo
+structure (unless
+.Fa p7
+is configured to store a detached signature) and the
+.Fa encryptedDigest
+fields in all the
+.Vt SignerInfo
+structures
+.It for Vt EnvelopedData No or Vt SignedAndEnvelopedData :
+the
+.Fa encryptedContent
+field in the
+.Vt EncryptedContentInfo
+structure contained in the
+.Fa content
+field of
+.Fa p7
+.It for arbitrary data :
+the
+.Fa content
+field of
+.Fa p7
+itself
+.El
+.Sh RETURN VALUES
+.Fn PKCS7_dataFinal
+returns 1 on success or 0 on failure.
+.Pp
+Possible reasons for failure include:
+.Pp
+.Bl -dash -compact -offset 2n -width 1n
+.It
+.Fa p7
+is
+.Dv NULL .
+.It
+The
+.Fa content
+field of
+.Fa p7
+is empty.
+.It
+The
+.Fa contentType
+of
+.Fa p7
+is unsupported.
+.It
+The
+.Fa chain
+does not contain the expected memory BIO.
+.It
+Signing or digesting is requested and
+.Fa p7
+is not configured to store a detached signature,
+but does not contain the required field to store the content either.
+.It
+At least one signer lacks a useable digest algorithm.
+.It
+Signing or digesting fails.
+.It
+Memory allocation fails.
+.El
+.Pp
+Signers lacking private keys do not cause failure
+but are silently skipped.
+.Sh SEE ALSO
+.Xr BIO_new 3 ,
+.Xr PKCS7_dataInit 3 ,
+.Xr PKCS7_new 3 ,
+.Xr PKCS7_sign 3
+.Sh HISTORY
+.Fn PKCS7_dataFinal
+first appeared in SSLeay 0.9.1 and has been available since
+.Ox 2.6 .
+.Sh CAVEATS
+This function does not support
+.Vt EncryptedData .
+.Pp
+Even though this function is typically used after
+.Xr PKCS7_dataInit 3
+and even though
+.Xr PKCS7_dataInit 3
+also supports reading from
+.Vt ContentInfo
+structures that are already fully populated, do not use
+.Fn PKCS7_dataFinal
+on fully populated structures.
+It is only intended for putting data into new structures
+and it is neither needed nor suitable for reading.
diff --git a/src/lib/libcrypto/man/PKCS7_new.3 b/src/lib/libcrypto/man/PKCS7_new.3
index c0943e021a..4abe3698e6 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.9 2020/05/24 12:37:30 schwarze Exp $
+.\" $OpenBSD: PKCS7_new.3,v 1.10 2020/05/27 12:00:44 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 24 2020 $
+.Dd $Mdocdate: May 27 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_dataFinal 3 ,
 .Xr PKCS7_dataInit 3 ,
 .Xr PKCS7_decrypt 3 ,
 .Xr PKCS7_encrypt 3 ,