From e17abbddd79622502d5988b8d2041d8c3cceee27 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 27 May 2020 12:00:44 +0000 Subject: document PKCS7_dataFinal(3); tweak and OK tb@ --- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/PKCS7_dataFinal.3 | 157 ++++++++++++++++++++++++++++++++ src/lib/libcrypto/man/PKCS7_new.3 | 5 +- 3 files changed, 162 insertions(+), 3 deletions(-) create mode 100644 src/lib/libcrypto/man/PKCS7_dataFinal.3 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 @@ -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 +.\" +.\" 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 .\" @@ -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 , -- cgit v1.2.3-55-g6feb