From 52f72375ae466a3914e02a33dcd4a545ee773d52 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Thu, 4 Jun 2020 10:24:27 +0000 Subject: [PATCH 05/87] new manual page PKCS7_add_attribute(3); tweaks and OK tb@ --- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/PKCS7_add_attribute.3 | 179 ++++++++++++++++++ src/lib/libcrypto/man/PKCS7_final.3 | 5 +- src/lib/libcrypto/man/PKCS7_new.3 | 5 +- src/lib/libcrypto/man/PKCS7_sign.3 | 9 +- src/lib/libcrypto/man/PKCS7_sign_add_signer.3 | 7 +- src/lib/libcrypto/man/X509_ATTRIBUTE_new.3 | 5 +- 7 files changed, 201 insertions(+), 12 deletions(-) create mode 100644 src/lib/libcrypto/man/PKCS7_add_attribute.3 diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 05b992e13..7effea837 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.165 2020/06/03 13:41:27 schwarze Exp $ +# $OpenBSD: Makefile,v 1.166 2020/06/04 10:24:27 schwarze Exp $ .include @@ -214,6 +214,7 @@ MAN= \ PKCS12_parse.3 \ PKCS12_SAFEBAG_new.3 \ PKCS5_PBKDF2_HMAC.3 \ + PKCS7_add_attribute.3 \ PKCS7_dataFinal.3 \ PKCS7_dataInit.3 \ PKCS7_decrypt.3 \ diff --git a/src/lib/libcrypto/man/PKCS7_add_attribute.3 b/src/lib/libcrypto/man/PKCS7_add_attribute.3 new file mode 100644 index 000000000..09c36a4d5 --- /dev/null +++ b/src/lib/libcrypto/man/PKCS7_add_attribute.3 @@ -0,0 +1,179 @@ +.\" $OpenBSD: PKCS7_add_attribute.3,v 1.1 2020/06/04 10:24: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 4 2020 $ +.Dt PKCS7_ADD_ATTRIBUTE 3 +.Os +.Sh NAME +.Nm PKCS7_add_attribute , +.Nm PKCS7_get_attribute , +.Nm PKCS7_add_signed_attribute , +.Nm PKCS7_get_signed_attribute +.Nd attributes of SignerInfo objects +.Sh SYNOPSIS +.In openssl/pkcs7.h +.Ft int +.Fo PKCS7_add_attribute +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "int nid" +.Fa "int attrtype" +.Fa "void *value" +.Fc +.Ft ASN1_TYPE * +.Fo PKCS7_get_attribute +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "int nid" +.Fc +.Ft int +.Fo PKCS7_add_signed_attribute +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "int nid" +.Fa "int attrtype" +.Fa "void *value" +.Fc +.Ft ASN1_TYPE * +.Fo PKCS7_get_signed_attribute +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "int nid" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_add_attribute +appends a new attribute of type +.Fa nid +to the +.Fa unauthenticatedAttributes +list of +.Fa si , +and it adds a new ASN.1 ANY object of type +.Fa attrtype +with the given +.Fa value +to the new attribute. +Ownership of the +.Fa value +is transferred into the new attribute object, so the calling code +must not +.Xr free 3 +the +.Fa value . +If the list already contains an unauthenticated attribute of type +.Fa nid +before the call, the new attribute replaces the old one +instead of being appended to the end of the list. +.Pp +.Fn PKCS7_get_attribute +retrieves the first ASN.1 ANY member of the attribute of type +.Fa nid +from the +.Fa unauthenticatedAttributes +list of +.Fa si . +.Pp +The behaviour of +.Fn PKCS7_add_signed_attribute +and +.Fn PKCS7_get_signed_attribute +is identical except that they operate on the list of +.Fa authenticatedAttributes . +.Pp +The normal way to use +.Fn PKCS7_add_signed_attribute +is to first create a +.Vt SignedInfo +object with +.Xr PKCS7_sign 3 +using the +.Dv PKCS7_PARTIAL +or +.Dv PKCS7_STREAM +flag, retrieve the +.Vt PKCS7_SIGNER_INFO +object with the undocumented function +.Fn PKCS7_get_signer_info +or add an additional one with +.Xr PKCS7_sign_add_signer 3 , +call +.Fn PKCS7_add_signed_attribute +for each desired additional attribute, then do the signing with +.Xr PKCS7_final 3 +or with another finalizing function. +.Pp +For particular types of attributes, undocumented wrapper functions +.Fn PKCS7_add_attrib_content_type , +.Fn PKCS7_add1_attrib_digest , +.Fn PKCS7_add0_attrib_signing_time , +and +.Fn PKCS7_add_attrib_smimecap +exist. +.Sh RETURN VALUES +.Fn PKCS7_add_attribute +and +.Fn PKCS7_add_signed_attribute +return 1 on success or 0 on failure. +The most common reason for failure is lack of memory. +.Pp +.Fn PKCS7_get_attribute +and +.Fn PKCS7_get_signed_attribute +return an internal pointer to an ASN.1 ANY object or +.Dv NULL +on failure. +They fail if +.Fa nid +is invalid, if the respective list in +.Fa si +contains no attribute of the requested type, or if an invalid element +is found in the list before finding the attribute of the requested type. +.Sh SEE ALSO +.Xr ASN1_TYPE_new 3 , +.Xr PKCS7_final 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_sign 3 , +.Xr PKCS7_sign_add_signer 3 , +.Xr STACK_OF 3 , +.Xr X509_ATTRIBUTE_new 3 +.Sh STANDARDS +RFC 2315: PKCS #7: Cryptographic Message Syntax Version 1.5, +section 9.2: SignerInfo type +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.1 +and have been available since +.Ox 2.6 . +.Sh BUGS +Adding an attribute with an invalid +.Fa nid +ought to fail, but it actually succeeds +setting the type of the new attribute to +.Dv NULL . +Subsequent attempts to retrieve attributes +may cause the program to crash due to +.Dv NULL +pointer access. +.Pp +A function to remove individual attributes from these lists +does not appear to exist. +A program desiring to do that might have to manually iterate the fields +.Fa auth_attr +and +.Fa unauth_attr +of +.Fa si , +which are both of type +.Vt STACK_OF(X509_ATTRIBUTE) , +using the facilities described in +.Xr STACK_OF 3 +and +.Xr OPENSSL_sk_new 3 . diff --git a/src/lib/libcrypto/man/PKCS7_final.3 b/src/lib/libcrypto/man/PKCS7_final.3 index 593483bb6..7c9e51521 100644 --- a/src/lib/libcrypto/man/PKCS7_final.3 +++ b/src/lib/libcrypto/man/PKCS7_final.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: PKCS7_final.3,v 1.1 2020/06/03 13:41:27 schwarze Exp $ +.\" $OpenBSD: PKCS7_final.3,v 1.2 2020/06/04 10:24: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: June 3 2020 $ +.Dd $Mdocdate: June 4 2020 $ .Dt PKCS7_FINAL 3 .Os .Sh NAME @@ -186,6 +186,7 @@ Signers lacking private keys do not cause failure but are silently skipped. .Xr BIO_new 3 , .Xr i2d_PKCS7_bio_stream 3 , .Xr PEM_write_bio_PKCS7_stream 3 , +.Xr PKCS7_add_attribute 3 , .Xr PKCS7_dataFinal 3 , .Xr PKCS7_dataInit 3 , .Xr PKCS7_encrypt 3 , diff --git a/src/lib/libcrypto/man/PKCS7_new.3 b/src/lib/libcrypto/man/PKCS7_new.3 index 4abe3698e..c5eebe96d 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.10 2020/05/27 12:00:44 schwarze Exp $ +.\" $OpenBSD: PKCS7_new.3,v 1.11 2020/06/04 10:24:27 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 27 2020 $ +.Dd $Mdocdate: June 4 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_add_attribute 3 , .Xr PKCS7_dataFinal 3 , .Xr PKCS7_dataInit 3 , .Xr PKCS7_decrypt 3 , diff --git a/src/lib/libcrypto/man/PKCS7_sign.3 b/src/lib/libcrypto/man/PKCS7_sign.3 index d5f4c89c6..c9b13680c 100644 --- a/src/lib/libcrypto/man/PKCS7_sign.3 +++ b/src/lib/libcrypto/man/PKCS7_sign.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: PKCS7_sign.3,v 1.11 2020/06/03 13:41:27 schwarze Exp $ +.\" $OpenBSD: PKCS7_sign.3,v 1.12 2020/06/04 10:24:27 schwarze Exp $ .\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 .\" .\" This file was written by Dr. Stephen Henson . @@ -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 3 2020 $ +.Dd $Mdocdate: June 4 2020 $ .Dt PKCS7_SIGN 3 .Os .Sh NAME @@ -196,7 +196,9 @@ if the .Dv PKCS7_PARTIAL flag is set. One or more signers can be added using the function -.Xr PKCS7_sign_add_signer 3 . +.Xr PKCS7_sign_add_signer 3 +and attributes can be added using the functions described in +.Xr PKCS7_add_attribute 3 . .Xr PKCS7_final 3 must also be called to finalize the structure if streaming is not enabled. @@ -228,6 +230,7 @@ if an error occurred. The error can be obtained from .Xr ERR_get_error 3 . .Sh SEE ALSO +.Xr PKCS7_add_attribute 3 , .Xr PKCS7_encrypt 3 , .Xr PKCS7_final 3 , .Xr PKCS7_new 3 , diff --git a/src/lib/libcrypto/man/PKCS7_sign_add_signer.3 b/src/lib/libcrypto/man/PKCS7_sign_add_signer.3 index f8024d9b5..28d327fef 100644 --- a/src/lib/libcrypto/man/PKCS7_sign_add_signer.3 +++ b/src/lib/libcrypto/man/PKCS7_sign_add_signer.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: PKCS7_sign_add_signer.3,v 1.11 2020/06/03 13:41:27 schwarze Exp $ +.\" $OpenBSD: PKCS7_sign_add_signer.3,v 1.12 2020/06/04 10:24:27 schwarze Exp $ .\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 .\" .\" This file was written by Dr. Stephen Henson . @@ -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 3 2020 $ +.Dd $Mdocdate: June 4 2020 $ .Dt PKCS7_SIGN_ADD_SIGNER 3 .Os .Sh NAME @@ -162,6 +162,8 @@ If any of these algorithms is disabled, then it will not be included. returns an internal pointer to the .Vt PKCS7_SIGNER_INFO structure just added, which can be used to set additional attributes +with the functions described in +.Xr PKCS7_add_attribute 3 before it is finalized. .Sh RETURN VALUES .Fn PKCS7_sign_add_signer @@ -174,6 +176,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_add_attribute 3 , .Xr PKCS7_final 3 , .Xr PKCS7_new 3 , .Xr PKCS7_sign 3 diff --git a/src/lib/libcrypto/man/X509_ATTRIBUTE_new.3 b/src/lib/libcrypto/man/X509_ATTRIBUTE_new.3 index b5c78ee8d..66779d637 100644 --- a/src/lib/libcrypto/man/X509_ATTRIBUTE_new.3 +++ b/src/lib/libcrypto/man/X509_ATTRIBUTE_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.7 2019/06/06 01:06:59 schwarze Exp $ +.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.8 2020/06/04 10:24:27 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: June 6 2019 $ +.Dd $Mdocdate: June 4 2020 $ .Dt X509_ATTRIBUTE_NEW 3 .Os .Sh NAME @@ -65,6 +65,7 @@ if an error occurs. .Sh SEE ALSO .Xr d2i_X509_ATTRIBUTE 3 , .Xr PKCS12_SAFEBAG_new 3 , +.Xr PKCS7_add_attribute 3 , .Xr PKCS8_PRIV_KEY_INFO_new 3 , .Xr X509_EXTENSION_new 3 , .Xr X509_new 3 , -- 2.17.1