describe six more PKCS7 attribute functions

1 files changed, 208 insertions, 14 deletions

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 <schwarze@openbsd.org>
 .\"
@@ -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.