From 4136b433281acfa0808344e5db0f77ec981c30ee Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 3 Jun 2020 13:41:27 +0000 Subject: [PATCH 03/87] Properly document PKCS7_final(3), which was already mentioned in passing in some other manual pages. --- src/lib/libcrypto/man/Makefile | 3 +- .../man/PEM_write_bio_PKCS7_stream.3 | 7 +- src/lib/libcrypto/man/PKCS7_dataFinal.3 | 5 +- src/lib/libcrypto/man/PKCS7_dataInit.3 | 25 ++- src/lib/libcrypto/man/PKCS7_encrypt.3 | 14 +- src/lib/libcrypto/man/PKCS7_final.3 | 201 ++++++++++++++++++ src/lib/libcrypto/man/PKCS7_sign.3 | 16 +- src/lib/libcrypto/man/PKCS7_sign_add_signer.3 | 9 +- src/lib/libcrypto/man/SMIME_write_PKCS7.3 | 8 +- src/lib/libcrypto/man/i2d_PKCS7_bio_stream.3 | 7 +- 10 files changed, 263 insertions(+), 32 deletions(-) create mode 100644 src/lib/libcrypto/man/PKCS7_final.3 diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 8af0c34d2..05b992e13 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.164 2020/05/27 12:00:44 schwarze Exp $ +# $OpenBSD: Makefile,v 1.165 2020/06/03 13:41:27 schwarze Exp $ .include @@ -218,6 +218,7 @@ MAN= \ PKCS7_dataInit.3 \ PKCS7_decrypt.3 \ PKCS7_encrypt.3 \ + PKCS7_final.3 \ PKCS7_new.3 \ PKCS7_set_content.3 \ PKCS7_set_type.3 \ diff --git a/src/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 b/src/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 index 91a1a5cd5..dba2a42a7 100644 --- a/src/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 +++ b/src/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 @@ -1,5 +1,5 @@ -.\" $OpenBSD: PEM_write_bio_PKCS7_stream.3,v 1.9 2019/06/14 13:59:32 schwarze Exp $ -.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" $OpenBSD: PEM_write_bio_PKCS7_stream.3,v 1.10 2020/06/03 13:41:27 schwarze Exp $ +.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 .\" .\" This file was written by Dr. Stephen Henson . .\" Copyright (c) 2007, 2009, 2016 The OpenSSL Project. All rights reserved. @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 14 2019 $ +.Dd $Mdocdate: June 3 2020 $ .Dt PEM_WRITE_BIO_PKCS7_STREAM 3 .Os .Sh NAME @@ -81,6 +81,7 @@ otherwise 0 is returned and an error code can be retrieved with .Xr BIO_new 3 , .Xr i2d_PKCS7_bio_stream 3 , .Xr PEM_write_PKCS7 3 , +.Xr PKCS7_final 3 , .Xr PKCS7_new 3 , .Xr SMIME_write_PKCS7 3 .Sh HISTORY diff --git a/src/lib/libcrypto/man/PKCS7_dataFinal.3 b/src/lib/libcrypto/man/PKCS7_dataFinal.3 index f9cdd62f6..e2e088d9d 100644 --- a/src/lib/libcrypto/man/PKCS7_dataFinal.3 +++ b/src/lib/libcrypto/man/PKCS7_dataFinal.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: PKCS7_dataFinal.3,v 1.1 2020/05/27 12:00:44 schwarze Exp $ +.\" $OpenBSD: PKCS7_dataFinal.3,v 1.2 2020/06/03 13:41:27 schwarze Exp $ .\" .\" Copyright (c) 2020 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 27 2020 $ +.Dd $Mdocdate: June 3 2020 $ .Dt PKCS7_DATAFINAL 3 .Os .Sh NAME @@ -134,6 +134,7 @@ but are silently skipped. .Sh SEE ALSO .Xr BIO_new 3 , .Xr PKCS7_dataInit 3 , +.Xr PKCS7_final 3 , .Xr PKCS7_new 3 , .Xr PKCS7_sign 3 .Sh HISTORY diff --git a/src/lib/libcrypto/man/PKCS7_dataInit.3 b/src/lib/libcrypto/man/PKCS7_dataInit.3 index 53090ff96..cb54d3f95 100644 --- a/src/lib/libcrypto/man/PKCS7_dataInit.3 +++ b/src/lib/libcrypto/man/PKCS7_dataInit.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: PKCS7_dataInit.3,v 1.1 2020/05/24 12:37:30 schwarze Exp $ +.\" $OpenBSD: PKCS7_dataInit.3,v 1.2 2020/06/03 13:41:27 schwarze Exp $ .\" .\" Copyright (c) 2020 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: June 3 2020 $ .Dt PKCS7_DATAINIT 3 .Os .Sh NAME @@ -110,6 +110,20 @@ are typically required to create to choose its desired type, and to allocate the nested .Vt ContentInfo structure. +Alternatively, for +.Vt SignedData , +.Xr PKCS7_sign 3 +can be used with the +.Dv PKCS7_PARTIAL +or +.Dv PKCS7_STREAM +.Fa flags +or for +.Vt EnvelopedData , +.Xr PKCS7_encrypt 3 +with the +.Dv PKCS7_STREAM +flag. .Pp After calling .Fn PKCS7_dataInit , @@ -130,7 +144,10 @@ does support the .Vt EnvelopedData and .Vt SignedAndEnvelopedData -types, using it for these types is awkward and error prone because +types, using it for these types is awkward and error prone +except when using +.Xr PKCS7_encrypt 3 +for the setup because .Xr PKCS7_content_new 3 does not support these two types. So in addition to creating @@ -183,6 +200,8 @@ or for various other reasons. .Xr BIO_read 3 , .Xr PKCS7_content_new 3 , .Xr PKCS7_dataFinal 3 , +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_final 3 , .Xr PKCS7_new 3 , .Xr PKCS7_set_type 3 , .Xr PKCS7_sign 3 diff --git a/src/lib/libcrypto/man/PKCS7_encrypt.3 b/src/lib/libcrypto/man/PKCS7_encrypt.3 index 4d1b435f1..700498a1d 100644 --- a/src/lib/libcrypto/man/PKCS7_encrypt.3 +++ b/src/lib/libcrypto/man/PKCS7_encrypt.3 @@ -1,5 +1,5 @@ -.\" $OpenBSD: PKCS7_encrypt.3,v 1.10 2019/06/10 14:58:48 schwarze Exp $ -.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" $OpenBSD: PKCS7_encrypt.3,v 1.11 2020/06/03 13:41:27 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 .\" .\" This file was written by Dr. Stephen Henson . .\" Copyright (c) 2002, 2006, 2007, 2008, 2009 The OpenSSL Project. @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 10 2019 $ +.Dd $Mdocdate: June 3 2020 $ .Dt PKCS7_ENCRYPT 3 .Os .Sh NAME @@ -133,11 +133,12 @@ properly finalize the .Vt PKCS7 structure will give unpredictable results. .Pp -Several functions, including +Several functions including +.Xr PKCS7_final 3 , .Xr SMIME_write_PKCS7 3 , -.Xr i2d_PKCS7_bio_stream 3 , -and .Xr PEM_write_bio_PKCS7_stream 3 , +and +.Xr i2d_PKCS7_bio_stream 3 finalize the structure. Alternatively finalization can be performed by obtaining the streaming ASN.1 @@ -155,6 +156,7 @@ The error can be obtained from .Xr ERR_get_error 3 . .Sh SEE ALSO .Xr PKCS7_decrypt 3 , +.Xr PKCS7_final 3 , .Xr PKCS7_new 3 , .Xr PKCS7_sign 3 .Sh HISTORY diff --git a/src/lib/libcrypto/man/PKCS7_final.3 b/src/lib/libcrypto/man/PKCS7_final.3 new file mode 100644 index 000000000..593483bb6 --- /dev/null +++ b/src/lib/libcrypto/man/PKCS7_final.3 @@ -0,0 +1,201 @@ +.\" $OpenBSD: PKCS7_final.3,v 1.1 2020/06/03 13:41:27 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: June 3 2020 $ +.Dt PKCS7_FINAL 3 +.Os +.Sh NAME +.Nm PKCS7_final +.Nd read data from a BIO into a ContentInfo object +.Sh SYNOPSIS +.In openssl/pkcs7.h +.Ft int +.Fo PKCS7_final +.Fa "PKCS7 *p7" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_final +reads +.Fa data +and puts it into the appropriate content field of +.Fa p7 +itself or of its appropriate substructure, which can be of type +.Vt SignedData , +.Vt EnvelopedData , +.Vt SignedAndEnvelopedData , +.Vt DigestedData , +or arbitrary data. +The +.Xr PKCS7_dataFinal 3 +manual explains which field exactly the data is put into. +.Pp +The following +.Fa flags +are recognized: +.Bl -tag -width PKCS7_BINARY +.It Dv PKCS7_BINARY +Copy the data verbatim without changing any bytes. +By default, line endings are replaced with two-byte +.Qq \er\en +sequences (ASCII CR+LF). +If this flag is set, +.Dv PKCS7_TEXT +is ignored. +.It Dv PKCS7_TEXT +Prepend +.Qq Content-Type: text/plain +followed by a blank line to the data. +This flag is ignored if +.Dv PKCS7_BINARY +is also set. +.El +.Pp +If any other bits are set in +.Fa flags , +for example +.Dv PKCS7_STREAM +or +.Dv PKCS7_PARTIAL , +they are ignored, allowing to pass the same +.Fa flags +argument that was already passed to +.Xr PKCS7_sign 3 +or +.Xr PKCS7_encrypt 3 . +.Pp +.Fn PKCS7_final +is most commonly used to finalize a +.Fa p7 +object returned from a call to +.Xr PKCS7_sign 3 +that used +.Fa flags +including +.Dv PKCS7_PARTIAL +or +.Dv PKCS7_STREAM . +With these flags, +.Xr PKCS7_sign 3 +ignores its +.Fa data +argument. +The partial +.Fa p7 +object returned can then be customized, for example setting up +multiple signers or non-default digest algorithms with +.Xr PKCS7_sign_add_signer 3 , +before calling +.Fn PKCS7_final . +.Pp +Similarly, +.Fn PKCS7_final +can be used to finalize a +.Fa p7 +object returned from a call to +.Xr PKCS7_encrypt 3 +that used +.Fa flags +including +.Dv PKCS7_STREAM . +.Pp +Since +.Fn PKCS7_final +starts by calling +.Xr PKCS7_dataInit 3 +internally, using it to finalize a +.Fa p7 +object containing +.Vt SignedAndEnvelopedData , +.Vt DigestedData , +or arbitrary data requires the setup described in the +.Xr PKCS7_dataInit 3 +manual. +For +.Vt SignedData +and +.Vt EnvelopedData , +such manual setup is also feasible, but it is more easily performed with +.Xr PKCS7_sign 3 +or +.Xr PKCS7_encrypt 3 , +respectively. +.Pp +.Fn PKCS7_final +is only one among several functions that can be used to finalize +.Fa p7 ; +alternatives include +.Xr SMIME_write_PKCS7 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , +and +.Xr i2d_PKCS7_bio_stream 3 . +.Sh RETURN VALUES +.Fn PKCS7_final +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 +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 +A cipher is required but none is configured. +.It +Any required operation fails, for example signing or digesting. +.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 i2d_PKCS7_bio_stream 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , +.Xr PKCS7_dataFinal 3 , +.Xr PKCS7_dataInit 3 , +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_sign 3 , +.Xr SMIME_write_PKCS7 3 +.Sh HISTORY +.Fn PKCS7_final +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Sh CAVEATS +This function does not support +.Vt EncryptedData . diff --git a/src/lib/libcrypto/man/PKCS7_sign.3 b/src/lib/libcrypto/man/PKCS7_sign.3 index a04e800ca..d5f4c89c6 100644 --- a/src/lib/libcrypto/man/PKCS7_sign.3 +++ b/src/lib/libcrypto/man/PKCS7_sign.3 @@ -1,5 +1,5 @@ -.\" $OpenBSD: PKCS7_sign.3,v 1.10 2019/06/10 14:58:48 schwarze Exp $ -.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" $OpenBSD: PKCS7_sign.3,v 1.11 2020/06/03 13:41:27 schwarze Exp $ +.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 .\" .\" This file was written by Dr. Stephen Henson . .\" Copyright (c) 2002, 2003, 2006-2009, 2015 The OpenSSL Project. @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 10 2019 $ +.Dd $Mdocdate: June 3 2020 $ .Dt PKCS7_SIGN 3 .Os .Sh NAME @@ -166,11 +166,12 @@ properly finalize the .Vt PKCS7 structure will give unpredictable results. .Pp -Several functions, including +Several functions including +.Xr PKCS7_final 3 , .Xr SMIME_write_PKCS7 3 , -.Xr i2d_PKCS7_bio_stream 3 , -and .Xr PEM_write_bio_PKCS7_stream 3 , +and +.Xr i2d_PKCS7_bio_stream 3 finalize the structure. Alternatively finalization can be performed by obtaining the streaming ASN.1 @@ -196,7 +197,7 @@ if the flag is set. One or more signers can be added using the function .Xr PKCS7_sign_add_signer 3 . -.Fn PKCS7_final +.Xr PKCS7_final 3 must also be called to finalize the structure if streaming is not enabled. Alternative signing digests can also be specified using this method. @@ -228,6 +229,7 @@ The error can be obtained from .Xr ERR_get_error 3 . .Sh SEE ALSO .Xr PKCS7_encrypt 3 , +.Xr PKCS7_final 3 , .Xr PKCS7_new 3 , .Xr PKCS7_sign_add_signer 3 , .Xr PKCS7_verify 3 diff --git a/src/lib/libcrypto/man/PKCS7_sign_add_signer.3 b/src/lib/libcrypto/man/PKCS7_sign_add_signer.3 index 41d57c2c2..f8024d9b5 100644 --- a/src/lib/libcrypto/man/PKCS7_sign_add_signer.3 +++ b/src/lib/libcrypto/man/PKCS7_sign_add_signer.3 @@ -1,5 +1,5 @@ -.\" $OpenBSD: PKCS7_sign_add_signer.3,v 1.10 2019/06/14 13:59:32 schwarze Exp $ -.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" $OpenBSD: PKCS7_sign_add_signer.3,v 1.11 2020/06/03 13:41:27 schwarze Exp $ +.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 .\" .\" This file was written by Dr. Stephen Henson . .\" Copyright (c) 2007, 2008, 2009, 2015 The OpenSSL Project. @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 14 2019 $ +.Dd $Mdocdate: June 3 2020 $ .Dt PKCS7_SIGN_ADD_SIGNER 3 .Os .Sh NAME @@ -100,7 +100,7 @@ flag is set, the returned .Dv PKCS7 structure is not complete and must be finalized either by streaming (if applicable) or by a call to -.Fn PKCS7_final . +.Xr PKCS7_final 3 . .Pp The main purpose of this function is to provide finer control over a PKCS#7 signed data structure where the simpler @@ -174,6 +174,7 @@ In some cases of failure, the reason can be determined with .Xr ERR_get_error 3 . .Sh SEE ALSO .Xr EVP_DigestInit 3 , +.Xr PKCS7_final 3 , .Xr PKCS7_new 3 , .Xr PKCS7_sign 3 .Sh HISTORY diff --git a/src/lib/libcrypto/man/SMIME_write_PKCS7.3 b/src/lib/libcrypto/man/SMIME_write_PKCS7.3 index 8baf6689a..39d8b5d85 100644 --- a/src/lib/libcrypto/man/SMIME_write_PKCS7.3 +++ b/src/lib/libcrypto/man/SMIME_write_PKCS7.3 @@ -1,5 +1,5 @@ -.\" $OpenBSD: SMIME_write_PKCS7.3,v 1.6 2019/06/14 13:59:32 schwarze Exp $ -.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" $OpenBSD: SMIME_write_PKCS7.3,v 1.7 2020/06/03 13:41:27 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" .\" This file was written by Dr. Stephen Henson . .\" Copyright (c) 2002, 2003, 2006, 2007, 2015 The OpenSSL Project. @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 14 2019 $ +.Dd $Mdocdate: June 3 2020 $ .Dt SMIME_WRITE_PKCS7 3 .Os .Sh NAME @@ -132,7 +132,9 @@ otherwise 0 is returned and an error code can be retrieved with .Xr ERR_get_error 3 . .Sh SEE ALSO .Xr i2d_PKCS7_bio_stream 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , .Xr PEM_write_PKCS7 3 , +.Xr PKCS7_final 3 , .Xr PKCS7_new 3 , .Xr SMIME_read_PKCS7 3 .Sh HISTORY diff --git a/src/lib/libcrypto/man/i2d_PKCS7_bio_stream.3 b/src/lib/libcrypto/man/i2d_PKCS7_bio_stream.3 index 463d861be..3d5df72b3 100644 --- a/src/lib/libcrypto/man/i2d_PKCS7_bio_stream.3 +++ b/src/lib/libcrypto/man/i2d_PKCS7_bio_stream.3 @@ -1,5 +1,5 @@ -.\" $OpenBSD: i2d_PKCS7_bio_stream.3,v 1.7 2018/03/23 04:34:23 schwarze Exp $ -.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" $OpenBSD: i2d_PKCS7_bio_stream.3,v 1.8 2020/06/03 13:41:27 schwarze Exp $ +.\" OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 .\" .\" This file was written by Dr. Stephen Henson . .\" Copyright (c) 2007, 2008, 2009, 2013 The OpenSSL Project. @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 23 2018 $ +.Dd $Mdocdate: June 3 2020 $ .Dt I2D_PKCS7_BIO_STREAM 3 .Os .Sh NAME @@ -82,6 +82,7 @@ returns 1 for success or 0 for failure. .Xr ERR_get_error 3 , .Xr PEM_write_bio_PKCS7_stream 3 , .Xr PEM_write_PKCS7 3 , +.Xr PKCS7_final 3 , .Xr PKCS7_new 3 , .Xr SMIME_write_PKCS7 3 .Sh HISTORY -- 2.17.1