NAME
PKCS7_add_attribute,
PKCS7_set_attributes,
PKCS7_get_attribute,
PKCS7_add_signed_attribute,
PKCS7_set_signed_attributes,
PKCS7_get_signed_attribute,
PKCS7_add_attrib_content_type,
PKCS7_add1_attrib_digest,
PKCS7_add0_attrib_signing_time,
PKCS7_add_attrib_smimecap —
attributes of SignerInfo
objects
SYNOPSIS
#include
<openssl/pkcs7.h>
int
PKCS7_add_attribute(PKCS7_SIGNER_INFO
*si, int nid, int
attrtype, void *value);
int
PKCS7_set_attributes(PKCS7_SIGNER_INFO
*si, STACK_OF(X509_ATTRIBUTE) *sk);
ASN1_TYPE *
PKCS7_get_attribute(PKCS7_SIGNER_INFO
*si, int nid);
int
PKCS7_add_signed_attribute(PKCS7_SIGNER_INFO
*si, int nid, int
attrtype, void *value);
int
PKCS7_set_signed_attributes(PKCS7_SIGNER_INFO
*si, STACK_OF(X509_ATTRIBUTE) *sk);
ASN1_TYPE *
PKCS7_get_signed_attribute(PKCS7_SIGNER_INFO
*si, int nid);
int
PKCS7_add_attrib_content_type(PKCS7_SIGNER_INFO
*si, ASN1_OBJECT *coid);
int
PKCS7_add1_attrib_digest(PKCS7_SIGNER_INFO
*si, const unsigned char *md,
int mdlen);
int
PKCS7_add0_attrib_signing_time(PKCS7_SIGNER_INFO
*si, ASN1_TIME *t);
int
PKCS7_add_attrib_smimecap(PKCS7_SIGNER_INFO
*si, STACK_OF(X509_ALGOR) *cap);
DESCRIPTION
PKCS7_add_attribute()
appends a new attribute of type nid to the
unauthenticatedAttributes list of
si, and it adds a new ASN.1 ANY object of type
attrtype with the given value to
the new attribute. Ownership of the value is
transferred into the new attribute object, so the calling code must not
free(3) the value. If the list already contains
an unauthenticated attribute of type nid before the
call, the new attribute replaces the old one instead of being appended to
the end of the list.
PKCS7_set_attributes()
frees the unauthenticatedAttributes list of
si and all the attributes contained in it and replaces
it with a deep copy of sk.
PKCS7_get_attribute()
retrieves the first ASN.1 ANY member of the attribute of type
nid from the
unauthenticatedAttributes list of
si.
The behaviour of
PKCS7_add_signed_attribute(),
PKCS7_set_signed_attributes(),
and
PKCS7_get_signed_attribute()
is identical except that they operate on the list of
authenticatedAttributes.
The normal way to use
PKCS7_add_signed_attribute()
is to first create a SignedInfo object with
PKCS7_sign(3) using the PKCS7_PARTIAL
or PKCS7_STREAM flag, retrieve the
PKCS7_SIGNER_INFO object with
PKCS7_get_signer_info(3) or add an additional one with
PKCS7_sign_add_signer(3), call
PKCS7_add_signed_attribute() for each desired
additional attribute, then do the signing with
PKCS7_final(3) or with another finalizing function.
The four remaining functions are
wrappers around
PKCS7_add_signed_attribute().
PKCS7_add_attrib_content_type()
sets the NID_pkcs9_contentType attribute to
coid, which specifies the content type of the
ContentInfo value to be signed. This attribute is
mandatory and automatically added by
PKCS7_sign(3) and
PKCS7_sign_add_signer(3) unless the
PKCS7_NOATTR flag is present. Objects suitable as
coid arguments can for example be obtained with
OBJ_nid2obj(3). If coid is
NULL, the content type defaults to
NID_pkcs7_data.
PKCS7_add1_attrib_digest()
sets or replaces the NID_pkcs9_messageDigest
attribute, which is the message digest of the contents octets of the
DER-encoding of the content field of the ContentInfo
value being signed, to a copy of md, which is assumed
to be mdlen bytes long. If mdlen
is -1, then
strlen(md)
is used instead of mdlen. This attribute is mandatory
and automatically added by
PKCS7_dataFinal(3) and
PKCS7_final(3).
PKCS7_add0_attrib_signing_time()
sets or replaces the optional NID_pkcs9_signingTime
attribute to t, specifying the time at which the
signer performed the signing process. Ownership of t
is transferred into the new attribute object, so the calling code must not
free(3) t. If t is
NULL, a new ASN1_TIME
structure is allocated. This attribute is automatically added by
PKCS7_dataFinal(3) and
PKCS7_final(3).
PKCS7_add_attrib_smimecap()
sets or replaces the optional NID_SMIMECapabilities
attribute, indicating algorithms the sender is prepared to handle. The
cap pointer is not stored in the new attribute object
and can be passed to
sk_X509_ALGOR_pop_free()
after the call. This attribute is automatically added by
PKCS7_sign(3) and
PKCS7_sign_add_signer(3) unless the
PKCS7_NOATTR or
PKCS7_NOSMIMECAP flag is present.
RETURN VALUES
PKCS7_add_attribute(),
PKCS7_set_attributes(),
PKCS7_add_signed_attribute(),
PKCS7_set_signed_attributes(),
PKCS7_add_attrib_content_type(),
PKCS7_add1_attrib_digest(),
PKCS7_add0_attrib_signing_time(), and
PKCS7_add_attrib_smimecap() return 1 on success or 0
on failure. The most common reason for failure is lack of memory.
PKCS7_add_attribute() and
PKCS7_add_signed_attribute() also fail if
nid is invalid, and
PKCS7_add_attrib_content_type() if
si already contains an authenticated attribute of type
NID_pkcs9_contentType.
PKCS7_get_attribute() and
PKCS7_get_signed_attribute() return an internal
pointer to an ASN.1 ANY object or NULL on failure.
They fail if nid is invalid, if the respective list in
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.
SEE ALSO
ASN1_TIME_new(3), ASN1_TYPE_new(3), OBJ_nid2obj(3), PKCS7_final(3), PKCS7_get_signer_info(3), PKCS7_new(3), PKCS7_sign(3), PKCS7_sign_add_signer(3), STACK_OF(3), X509_ALGOR_new(3), X509_ATTRIBUTE_new(3)
STANDARDS
RFC 2315: PKCS #7: Cryptographic Message Syntax Version 1.5, section 9.2: SignerInfo type
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
RFC 8551: Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 4.0 Message Specification, section 2.5.2: SMIMECapabilities Attribute
HISTORY
PKCS7_add_attribute(),
PKCS7_set_attributes(),
PKCS7_get_attribute(),
PKCS7_add_signed_attribute(),
PKCS7_set_signed_attributes(), and
PKCS7_get_signed_attribute() first appeared in
OpenSSL 0.9.1 and have been available since OpenBSD
2.6.
PKCS7_add_attrib_smimecap() first appeared
in OpenSSL 0.9.5 and has been available since OpenBSD
2.7.
PKCS7_add_attrib_content_type(),
PKCS7_add1_attrib_digest(), and
PKCS7_add0_attrib_signing_time() first appeared in
OpenSSL 1.0.0 and have been available since OpenBSD
4.9.
CAVEATS
PKCS7_set_signed_attributes() does not
validate that sk contains the PKCS #9 content type and
message digest attributes required by RFC 2315. It succeeds even when
sk is empty, leaving si in a
state that violates the standard.
PKCS7_add0_attrib_signing_time() does not
validate t in any way. In particular, it may set the
signing time to the future or to the remote past.
BUGS
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 auth_attr and unauth_attr of si, which are both of type STACK_OF(X509_ATTRIBUTE), using the facilities described in STACK_OF(3) and OPENSSL_sk_new(3).