From e8af5db3e70d60b37bbbfbfcd578fd6e92cff350 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 10 Jun 2020 11:39:12 +0000 Subject: describe six more PKCS7 attribute functions --- src/lib/libcrypto/man/PKCS7_add_attribute.3 | 222 ++++++++++++++++++++++++++-- 1 file changed, 208 insertions(+), 14 deletions(-) (limited to 'src') diff --git a/src/lib/libcrypto/man/PKCS7_add_attribute.3 b/src/lib/libcrypto/man/PKCS7_add_attribute.3 index 081703f0f3..4a1c350f98 100644 --- a/src/lib/libcrypto/man/PKCS7_add_attribute.3 +++ b/src/lib/libcrypto/man/PKCS7_add_attribute.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: PKCS7_add_attribute.3,v 1.2 2020/06/04 21:21:03 schwarze Exp $ +.\" $OpenBSD: PKCS7_add_attribute.3,v 1.3 2020/06/10 11:39:12 schwarze Exp $ .\" .\" Copyright (c) 2020 Ingo Schwarze .\" @@ -14,14 +14,20 @@ .\" 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 $ +.Dd $Mdocdate: June 10 2020 $ .Dt PKCS7_ADD_ATTRIBUTE 3 .Os .Sh NAME .Nm PKCS7_add_attribute , +.Nm PKCS7_set_attributes , .Nm PKCS7_get_attribute , .Nm PKCS7_add_signed_attribute , -.Nm PKCS7_get_signed_attribute +.Nm PKCS7_set_signed_attributes , +.Nm PKCS7_get_signed_attribute , +.Nm PKCS7_add_attrib_content_type , +.Nm PKCS7_add1_attrib_digest , +.Nm PKCS7_add0_attrib_signing_time , +.Nm PKCS7_add_attrib_smimecap .Nd attributes of SignerInfo objects .Sh SYNOPSIS .In openssl/pkcs7.h @@ -32,6 +38,11 @@ .Fa "int attrtype" .Fa "void *value" .Fc +.Ft int +.Fo PKCS7_set_attributes +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "STACK_OF(X509_ATTRIBUTE) *sk" +.Fc .Ft ASN1_TYPE * .Fo PKCS7_get_attribute .Fa "PKCS7_SIGNER_INFO *si" @@ -44,11 +55,37 @@ .Fa "int attrtype" .Fa "void *value" .Fc +.Ft int +.Fo PKCS7_set_signed_attributes +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "STACK_OF(X509_ATTRIBUTE) *sk" +.Fc .Ft ASN1_TYPE * .Fo PKCS7_get_signed_attribute .Fa "PKCS7_SIGNER_INFO *si" .Fa "int nid" .Fc +.Ft int +.Fo PKCS7_add_attrib_content_type +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "ASN1_OBJECT *coid" +.Fc +.Ft int +.Fo PKCS7_add1_attrib_digest +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "const unsigned char *md" +.Fa "int mdlen" +.Fc +.Ft int +.Fo PKCS7_add0_attrib_signing_time +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "ASN1_TIME *t" +.Fc +.Ft int +.Fo PKCS7_add_attrib_smimecap +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "STACK_OF(X509_ALGOR) *cap" +.Fc .Sh DESCRIPTION .Fn PKCS7_add_attribute appends a new attribute of type @@ -74,6 +111,14 @@ If the list already contains an unauthenticated attribute of type before the call, the new attribute replaces the old one instead of being appended to the end of the list. .Pp +.Fn PKCS7_set_attributes +frees the +.Fa unauthenticatedAttributes +list of +.Fa si +and all the attributes contained in it and replaces it with a deep copy of +.Fa sk . +.Pp .Fn PKCS7_get_attribute retrieves the first ASN.1 ANY member of the attribute of type .Fa nid @@ -83,7 +128,8 @@ list of .Fa si . .Pp The behaviour of -.Fn PKCS7_add_signed_attribute +.Fn PKCS7_add_signed_attribute , +.Fn PKCS7_set_signed_attributes , and .Fn PKCS7_get_signed_attribute is identical except that they operate on the list of @@ -101,8 +147,8 @@ or .Dv PKCS7_STREAM flag, retrieve the .Vt PKCS7_SIGNER_INFO -object with the undocumented function -.Fn PKCS7_get_signer_info +object with +.Xr PKCS7_get_signer_info 3 or add an additional one with .Xr PKCS7_sign_add_signer 3 , call @@ -111,21 +157,122 @@ 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 +The four remaining functions are wrappers around +.Fn PKCS7_add_signed_attribute . +.Pp +.Fn PKCS7_add_attrib_content_type +sets the +.Dv NID_pkcs9_contentType +attribute to +.Fa coid , +which specifies the content type of the +.Vt ContentInfo +value to be signed. +This attribute is mandatory and automatically added by +.Xr PKCS7_sign 3 +and +.Xr PKCS7_sign_add_signer 3 +unless the +.Dv PKCS7_NOATTR +flag is present. +Objects suitable as +.Fa coid +arguments can for example be obtained with +.Xr OBJ_nid2obj 3 . +If +.Fa coid +is +.Dv NULL , +the content type defaults to +.Dv NID_pkcs7_data . +.Pp +.Fn PKCS7_add1_attrib_digest +sets or replaces the +.Dv NID_pkcs9_messageDigest +attribute, which is the message digest of the contents octets +of the DER-encoding of the content field of the +.Vt ContentInfo +value being signed, to a copy of +.Fa md , +which is assumed to be +.Fa mdlen +bytes long. +If +.Fa mdlen +is -1, then +.Fn strlen md +is used instead of +.Fa mdlen . +This attribute is mandatory and automatically added by +.Xr PKCS7_dataFinal 3 +and +.Xr PKCS7_final 3 . +.Pp +.Fn PKCS7_add0_attrib_signing_time +sets or replaces the optional +.Dv NID_pkcs9_signingTime +attribute to +.Fa t , +specifying the time at which the signer performed the signing process. +Ownership of +.Fa t +is transferred into the new attribute object, so the calling code +must not +.Xr free 3 +.Fa t . +If +.Fa t +is +.Dv NULL , +a new +.Vt ASN1_TIME +structure is allocated. +This attribute is automatically added by +.Xr PKCS7_dataFinal 3 +and +.Xr PKCS7_final 3 . +.Pp +.Fn PKCS7_add_attrib_smimecap +sets or replaces the optional +.Dv NID_SMIMECapabilities +attribute, indicating algorithms the sender is prepared to handle. +The +.Fa cap +pointer is not stored in the new attribute object and can be passed to +.Fn sk_X509_ALGOR_pop_free +after the call. +This attribute is automatically added by +.Xr PKCS7_sign 3 +and +.Xr PKCS7_sign_add_signer 3 +unless the +.Dv PKCS7_NOATTR +or +.Dv PKCS7_NOSMIMECAP +flag is present. +.Sh RETURN VALUES +.Fn PKCS7_add_attribute , +.Fn PKCS7_set_attributes , +.Fn PKCS7_add_signed_attribute , +.Fn PKCS7_set_signed_attributes , .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 +return 1 on success or 0 on failure. +The most common reason for failure is lack of memory. .Fn PKCS7_add_attribute and .Fn PKCS7_add_signed_attribute -return 1 on success or 0 on failure. -The most common reasons for failure are an invalid +also fail if .Fa nid -argument or lack of memory. +is invalid, and +.Fn PKCS7_add_attrib_content_type +if +.Fa si +already contains an authenticated attribute of type +.Dv NID_pkcs9_contentType . .Pp .Fn PKCS7_get_attribute and @@ -140,20 +287,67 @@ is invalid, if the respective list in 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_TIME_new 3 , .Xr ASN1_TYPE_new 3 , +.Xr OBJ_nid2obj 3 , .Xr PKCS7_final 3 , +.Xr PKCS7_get_signer_info 3 , .Xr PKCS7_new 3 , .Xr PKCS7_sign 3 , .Xr PKCS7_sign_add_signer 3 , .Xr STACK_OF 3 , +.Xr X509_ALGOR_new 3 , .Xr X509_ATTRIBUTE_new 3 .Sh STANDARDS RFC 2315: PKCS #7: Cryptographic Message Syntax Version 1.5, section 9.2: SignerInfo type +.Pp +RFC 2985: PKCS #9: Selected Object Classes and Attribute Types Version 2.0, +section 5.3: Attribute types for use in PKCS #7 data +and section 5.6: Attributes defined in S/MIME +.Pp +RFC 8551: Secure/Multipurpose Internet Mail Extensions (S/MIME) +Version 4.0 Message Specification, +section 2.5.2: SMIMECapabilities Attribute .Sh HISTORY -These functions first appeared in OpenSSL 0.9.1 -and have been available since +.Fn PKCS7_add_attribute , +.Fn PKCS7_set_attributes , +.Fn PKCS7_get_attribute , +.Fn PKCS7_add_signed_attribute , +.Fn PKCS7_set_signed_attributes , +and +.Fn PKCS7_get_signed_attribute +first appeared in OpenSSL 0.9.1 and have been available since .Ox 2.6 . +.Pp +.Fn PKCS7_add_attrib_smimecap +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +.Fn PKCS7_add_attrib_content_type , +.Fn PKCS7_add1_attrib_digest , +and +.Fn PKCS7_add0_attrib_signing_time +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Sh CAVEATS +.Fn PKCS7_set_signed_attributes +does not validate that +.Fa sk +contains the PKCS #9 content type and message digest attributes +required by RFC 2315. +It succeeds even when +.Fa sk +is empty, leaving +.Fa si +in a state that violates the standard. +.Pp +.Fn PKCS7_add0_attrib_signing_time +does not validate +.Fa t +in any way. +In particular, it may set the signing time to the future +or to the remote past. .Sh BUGS A function to remove individual attributes from these lists does not appear to exist. -- cgit v1.2.3-55-g6feb