NAME¶

CMS_signed_add1_attr, CMS_signed_add1_attr_by_NID, CMS_signed_add1_attr_by_OBJ, CMS_signed_add1_attr_by_txt, CMS_signed_delete_attr, CMS_signed_get0_data_by_OBJ, CMS_signed_get_attr, CMS_signed_get_attr_by_NID, CMS_signed_get_attr_by_OBJ, CMS_signed_get_attr_count, CMS_unsigned_add1_attr, CMS_unsigned_add1_attr_by_NID, CMS_unsigned_add1_attr_by_OBJ, CMS_unsigned_add1_attr_by_txt, CMS_unsigned_delete_attr, CMS_unsigned_get0_data_by_OBJ, CMS_unsigned_get_attr, CMS_unsigned_get_attr_by_NID, CMS_unsigned_get_attr_by_OBJ, CMS_unsigned_get_attr_count — change signed and unsigned attributes of a CMS SignerInfo object

SYNOPSIS¶

#include <openssl/cms.h>

int
CMS_signed_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr);

int
CMS_signed_add1_attr_by_NID(CMS_SignerInfo *si, int nid, int type, const void *bytes, int len);

int
CMS_signed_add1_attr_by_OBJ(CMS_SignerInfo *si, const ASN1_OBJECT *obj, int type, const void *bytes, int len);

int
CMS_signed_add1_attr_by_txt(CMS_SignerInfo *si, const char *attrname, int type, const void *bytes, int len);

X509_ATTRIBUTE *
CMS_signed_delete_attr(CMS_SignerInfo *si, int loc);

void *
CMS_signed_get0_data_by_OBJ(CMS_SignerInfo *si, const ASN1_OBJECT *oid, int start_after, int type);

X509_ATTRIBUTE *
CMS_signed_get_attr(const CMS_SignerInfo *si, int loc);

int
CMS_signed_get_attr_by_NID(const CMS_SignerInfo *si, int nid, int start_after);

int
CMS_signed_get_attr_by_OBJ(const CMS_SignerInfo *si, const ASN1_OBJECT *obj, int start_after);

int
CMS_signed_get_attr_count(const CMS_SignerInfo *si);

int
CMS_unsigned_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr);

int
CMS_unsigned_add1_attr_by_NID(CMS_SignerInfo *si, int nid, int type, const void *bytes, int len);

int
CMS_unsigned_add1_attr_by_OBJ(CMS_SignerInfo *si, const ASN1_OBJECT *obj, int type, const void *bytes, int len);

int
CMS_unsigned_add1_attr_by_txt(CMS_SignerInfo *si, const char *attrname, int type, const void *bytes, int len);

X509_ATTRIBUTE *
CMS_unsigned_delete_attr(CMS_SignerInfo *si, int loc);

void *
CMS_unsigned_get0_data_by_OBJ(CMS_SignerInfo *si, ASN1_OBJECT *oid, int start_after, int type);

X509_ATTRIBUTE *
CMS_unsigned_get_attr(const CMS_SignerInfo *si, int loc);

int
CMS_unsigned_get_attr_by_NID(const CMS_SignerInfo *si, int nid, int start_after);

int
CMS_unsigned_get_attr_by_OBJ(const CMS_SignerInfo *si, const ASN1_OBJECT *obj, int start_after);

int
CMS_unsigned_get_attr_count(const CMS_SignerInfo *si);

DESCRIPTION¶

A CMS_SignerInfo object has two optional sets of X.501 attributes: a set of signed attributes in the signedAttrs array and a set of unsigned attributes in the unsignedAttrs array. The CMS_signed_*() and CMS_unsigned_*() functions are similar, except CMS_signed_*() modifies the CMS_SignerInfo object's set of signed attributes and CMS_unsigned_*() modifies the CMS_SignerInfo object's set of unsigned attributes. For brevity only the CMS_signed_*() functions are described below.

CMS_signed_add1_attr() appends a deep copy of attr to the signedAttrs array of si, allocating a new array if necessary.

CMS_signed_add1_attr_by_NID(), CMS_signed_add1_attr_by_OBJ(), and CMS_signed_add1_attr_by_txt() create a new X.501 Attribute object using X509_ATTRIBUTE_create_by_NID(3), X509_ATTRIBUTE_create_by_OBJ(3), or X509_ATTRIBUTE_create_by_txt(3), respectively, and append it to the signedAttrs array of si.

CMS_signed_delete_attr() deletes the element with the zero-based loc in signedAttrs of si.

CMS_signed_get0_data_by_OBJ(), CMS_signed_get_attr_by_NID(), and CMS_signed_get_attr_by_OBJ() search the array starting after the index start_after. They fail if no matching object is found. CMS_signed_get0_data_by_OBJ() also fails if the data is not of the requested type.

Additionally, the start_after argument of CMS_signed_get0_data_by_OBJ() is interpreted in a special way. If start_after is -2 or smaller, the function also fails if the signedAttrs array of si, contains more than one matching object. If start_after is -3 or smaller, it also fails unless the matching object contains exactly one value.

CMS_signed_get_attr() returns the array element at the zero-based loc. It fails if the loc argument is negative or greater than or equal to the number of objects in the array.

CMS_signed_get_attr_count() returns the number of objects currently stored in the signedAttrs array of si.

RETURN VALUES¶

CMS_signed_add1_attr(), CMS_signed_add1_attr_by_NID(), CMS_signed_add1_attr_by_OBJ(), CMS_signed_add1_attr_by_txt(), CMS_unsigned_add1_attr(), CMS_unsigned_add1_attr_by_NID(), CMS_unsigned_add1_attr_by_OBJ(), and CMS_unsigned_add1_attr_by_txt() return 1 for success or 0 if an error occurs.

CMS_signed_delete_attr() returns the deleted element or NULL if the signedAttrs array is NULL, or if the requested loc argument is negative, or greater than or equal to the number of objects in it.

CMS_unsigned_delete_attr() returns the deleted element or NULL if the unsignedAttrs array is NULL, or if the requested loc argument is negative, or greater than or equal to the number of objects in it.

CMS_signed_get0_data_by_OBJ() and CMS_unsigned_get0_data_by_OBJ() return an internal pointer to the data contained in the value of the first object that has an index greater than start_after and a type matching type, or NULL on failure.

CMS_signed_get_attr() and CMS_unsigned_get_attr() return an internal pointer or NULL on failure.

CMS_signed_get_attr_by_NID(), CMS_signed_get_attr_by_OBJ(), CMS_unsigned_get_attr_by_NID(), and CMS_unsigned_get_attr_by_OBJ() return the index of the first object in the array that has an index greater than start_after and a type matching nid or oid, respectively, or -1 on failure. In addition, CMS_signed_get_attr_by_OBJ() and CMS_unsigned_get_attr_by_OBJ() return -2 if OBJ_nid2obj(3) fails on the requested nid.

CMS_signed_get_attr_count() and CMS_unsigned_get_attr_count() return the number of array elements or -1 on failure.

SEE ALSO¶

CMS_add1_signer(3), CMS_ContentInfo_new(3), CMS_get0_SignerInfos(3), OBJ_nid2obj(3), X509_ATTRIBUTE_create_by_OBJ(3), X509_ATTRIBUTE_new(3)

STANDARDS¶

RFC 5652: Cryptographic Message Syntax (CMS)

• section 5.3: SignerInfo Type
• section 11: Useful Attributes

HISTORY¶

These functions first appeared in OpenSSL 0.9.9 and have been available since OpenBSD 6.6.