From 3897abf3f7fbae4cfd94912a4a3ccdcbbfe8470a Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sun, 24 May 2020 12:37:30 +0000 Subject: 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. --- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/PKCS7_dataInit.3 | 207 ++++++++++++++++++++++++++++++ src/lib/libcrypto/man/PKCS7_new.3 | 5 +- src/lib/libcrypto/man/PKCS7_set_content.3 | 5 +- 4 files changed, 215 insertions(+), 5 deletions(-) create mode 100644 src/lib/libcrypto/man/PKCS7_dataInit.3 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 @@ -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 +.\" +.\" 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 .\" @@ -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 .\" @@ -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 -- cgit v1.2.3-55-g6feb