PKCS7_ADD_ATTRIBUTE(3)

📦 version 4.1.0, in opensuse-leap 16.0

🎀 NAME 🎀

okay bestie, welcome to PKCS7_ADD_ATTRIBUTE(3) — literally the manual page for the attribute-handling squad of SignerInfo objects. The whole crew is: 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, and 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 💖

okay so these functions are all about poking at the attribute lists hanging off a PKCS7_SIGNER_INFO (si). The two lists that matter are unauthenticatedAttributes and authenticatedAttributes. The vibe check is: add stuff, set whole stacks, get stuff back, and know which list you’re touching. 💅

  • 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 that new attribute. Ownership of 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. no duplicates, bestie. 💀
  • PKCS7_set_attributes() — frees the unauthenticatedAttributes list of si and all the attributes contained in it, then replaces it with a deep copy of sk. it’s giving “out with the old, in with the clone.” 🦋
  • PKCS7_get_attribute() — retrieves the first ASN.1 ANY member of the attribute of type nid from the unauthenticatedAttributes list of si.
  • PKCS7_add_signed_attribute(), PKCS7_set_signed_attributes(), and PKCS7_get_signed_attribute() — behaviour is identical except that they operate on the list of authenticatedAttributes. same energy, different list. ✨

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. that’s the whole routine, and it slays. 🔥

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. vibe check failed, return NULL. 💀

🦋 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. the OGs fr fr.
  • 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. not the flex you think it is. 🙈
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. time travel? in my signing attribute? it’s more likely than you think. ⏳

💀 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). manual looping era, lowkey tragic. 😭

mwah 💋 — this page is from the Debian edition, dated June 10, 2020, for PKCS7_ADD_ATTRIBUTE(3). periodt. 💅

📦 where this page comes from