CMS_SIGNED_ADD1_ATTR(3) | Library Functions Manual | CMS_SIGNED_ADD1_ATTR(3)

# 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

library “libcrypto”
`#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.

June 13, 2025 | Debian