1=pod 2 3=head1 NAME 4 5CMS_signed_get_attr_count, 6CMS_signed_get_attr_by_NID, CMS_signed_get_attr_by_OBJ, CMS_signed_get_attr, 7CMS_signed_delete_attr, 8CMS_signed_add1_attr, CMS_signed_add1_attr_by_OBJ, 9CMS_signed_add1_attr_by_NID, CMS_signed_add1_attr_by_txt, 10CMS_signed_get0_data_by_OBJ, 11CMS_unsigned_get_attr_count, 12CMS_unsigned_get_attr_by_NID, CMS_unsigned_get_attr_by_OBJ, 13CMS_unsigned_get_attr, CMS_unsigned_delete_attr, 14CMS_unsigned_add1_attr, CMS_unsigned_add1_attr_by_OBJ, 15CMS_unsigned_add1_attr_by_NID, CMS_unsigned_add1_attr_by_txt, 16CMS_unsigned_get0_data_by_OBJ 17- CMS signed and unsigned attribute functions 18 19=head1 SYNOPSIS 20 21 #include <openssl/cms.h> 22 23 int CMS_signed_get_attr_count(const CMS_SignerInfo *si); 24 int CMS_signed_get_attr_by_NID(const CMS_SignerInfo *si, int nid, 25 int lastpos); 26 int CMS_signed_get_attr_by_OBJ(const CMS_SignerInfo *si, const ASN1_OBJECT *obj, 27 int lastpos); 28 X509_ATTRIBUTE *CMS_signed_get_attr(const CMS_SignerInfo *si, int loc); 29 X509_ATTRIBUTE *CMS_signed_delete_attr(CMS_SignerInfo *si, int loc); 30 int CMS_signed_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr); 31 int CMS_signed_add1_attr_by_OBJ(CMS_SignerInfo *si, 32 const ASN1_OBJECT *obj, int type, 33 const void *bytes, int len); 34 int CMS_signed_add1_attr_by_NID(CMS_SignerInfo *si, 35 int nid, int type, 36 const void *bytes, int len); 37 int CMS_signed_add1_attr_by_txt(CMS_SignerInfo *si, 38 const char *attrname, int type, 39 const void *bytes, int len); 40 void *CMS_signed_get0_data_by_OBJ(const CMS_SignerInfo *si, 41 const ASN1_OBJECT *oid, 42 int lastpos, int type); 43 44 int CMS_unsigned_get_attr_count(const CMS_SignerInfo *si); 45 int CMS_unsigned_get_attr_by_NID(const CMS_SignerInfo *si, int nid, 46 int lastpos); 47 int CMS_unsigned_get_attr_by_OBJ(const CMS_SignerInfo *si, 48 const ASN1_OBJECT *obj, int lastpos); 49 X509_ATTRIBUTE *CMS_unsigned_get_attr(const CMS_SignerInfo *si, int loc); 50 X509_ATTRIBUTE *CMS_unsigned_delete_attr(CMS_SignerInfo *si, int loc); 51 int CMS_unsigned_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr); 52 int CMS_unsigned_add1_attr_by_OBJ(CMS_SignerInfo *si, 53 const ASN1_OBJECT *obj, int type, 54 const void *bytes, int len); 55 int CMS_unsigned_add1_attr_by_NID(CMS_SignerInfo *si, 56 int nid, int type, 57 const void *bytes, int len); 58 int CMS_unsigned_add1_attr_by_txt(CMS_SignerInfo *si, 59 const char *attrname, int type, 60 const void *bytes, int len); 61 void *CMS_unsigned_get0_data_by_OBJ(CMS_SignerInfo *si, ASN1_OBJECT *oid, 62 int lastpos, int type); 63 64=head1 DESCRIPTION 65 66CMS_signerInfo contains separate attribute lists for signed and unsigned 67attributes. Each CMS_signed_XXX() function is used for signed attributes, and 68each CMS_unsigned_XXX() function is used for unsigned attributes. 69Since the CMS_unsigned_XXX() functions work in the same way as the 70CMS_signed_XXX() equivalents, only the CMS_signed_XXX() functions are 71described below. 72 73CMS_signed_get_attr_by_OBJ() finds the location of the first matching object 74I<obj> in the SignerInfo's I<si> signed attribute list. The search starts at the 75position after I<lastpos>. If the returned value is positive then it can be used 76on the next call to CMS_signed_get_attr_by_OBJ() as the value of I<lastpos> in 77order to iterate through the remaining attributes. I<lastpos> can be set to any 78negative value on the first call, in order to start searching from the start of 79the signed attribute list. 80 81CMS_signed_get_attr_by_NID() is similar to CMS_signed_get_attr_by_OBJ() except 82that it passes the numerical identifier (NID) I<nid> associated with the object. 83See <openssl/obj_mac.h> for a list of NID_*. 84 85CMS_signed_get_attr() returns the B<X509_ATTRIBUTE> object at index I<loc> in the 86I<si> signed attribute list. I<loc> should be in the range from 0 to 87CMS_signed_get_attr_count() - 1. 88 89CMS_signed_delete_attr() removes the B<X509_ATTRIBUTE> object at index I<loc> in 90the I<si> signed attribute list. An error occurs if the I<si> attribute list 91is NULL. 92 93CMS_signed_add1_attr() pushes a copy of the passed in B<X509_ATTRIBUTE> object 94to the I<si> signed attribute list. A new signed attribute list is created if 95required. An error occurs if I<attr> is NULL. 96 97CMS_signed_add1_attr_by_OBJ() creates a new signed B<X509_ATTRIBUTE> using 98X509_ATTRIBUTE_set1_object() and X509_ATTRIBUTE_set1_data() to assign a new 99I<obj> with type I<type> and data I<bytes> of length I<len> and then pushes it 100to the I<key> object's attribute list. 101 102CMS_signed_add1_attr_by_NID() is similar to CMS_signed_add1_attr_by_OBJ() except 103that it passes the numerical identifier (NID) I<nid> associated with the object. 104See <openssl/obj_mac.h> for a list of NID_*. 105 106CMS_signed_add1_attr_by_txt() is similar to CMS_signed_add1_attr_by_OBJ() 107except that it passes a name I<attrname> associated with the object. 108See <openssl/obj_mac.h> for a list of SN_* names. 109 110CMS_signed_get0_data_by_OBJ() finds the first attribute in a I<si> signed 111attributes list that matches the I<obj> starting at index I<lastpos> 112and returns the data retrieved from the found attributes first B<ASN1_TYPE> 113object. An error will occur if the attribute type I<type> does not match the 114type of the B<ASN1_TYPE> object OR if I<type> is either B<V_ASN1_BOOLEAN> or 115B<V_ASN1_NULL> OR the attribute is not found. 116If I<lastpos> is less than -1 then an error will occur if there are multiple 117objects in the signed attribute list that match I<obj>. 118If I<lastpos> is less than -2 then an error will occur if there is more than 119one B<ASN1_TYPE> object in the found signed attribute. 120 121Refer to L<X509_ATTRIBUTE(3)> for information related to attributes. 122 123=head1 RETURN VALUES 124 125The CMS_unsigned_XXX() functions return values are similar to those of the 126equivalent CMS_signed_XXX() functions. 127 128CMS_signed_get_attr_count() returns the number of signed attributes in the 129SignerInfo I<si>, or -1 if the signed attribute list is NULL. 130 131CMS_signed_get_attr_by_OBJ() returns -1 if either the signed attribute list of 132I<si> is empty OR if I<obj> is not found, otherwise it returns the location of 133the I<obj> in the SignerInfo's I<si> signed attribute list. 134 135CMS_signed_get_attr_by_NID() is similar to CMS_signed_get_attr_by_OBJ() except 136that it returns -2 if the I<nid> is not known by OpenSSL. 137 138CMS_signed_get_attr() returns either a signed B<X509_ATTRIBUTE> or NULL on error. 139 140CMS_signed_delete_attr() returns either the removed signed B<X509_ATTRIBUTE> or 141NULL if there is a error. 142 143CMS_signed_add1_attr(), CMS_signed_add1_attr_by_OBJ(), 144CMS_signed_add1_attr_by_NID(), CMS_signed_add1_attr_by_txt(), 145return 1 on success or 0 on error. 146 147CMS_signed_get0_data_by_OBJ() returns the data retrieved from the found 148signed attributes first B<ASN1_TYPE> object, or NULL if an error occurs. 149 150=head1 NOTES 151 152Some attributes are added automatically during the signing process. 153 154Calling CMS_SignerInfo_sign() adds the NID_pkcs9_signingTime signed 155attribute. 156 157Calling CMS_final(), CMS_final_digest() or CMS_dataFinal() adds the 158NID_pkcs9_messageDigest signed attribute. 159 160The NID_pkcs9_contentType signed attribute is always added if the 161NID_pkcs9_signingTime attribute is added. 162 163Calling CMS_sign_ex(), CMS_sign_receipt() or CMS_add1_signer() may add 164attributes depending on the flags parameter. See L<CMS_add1_signer(3)> for 165more information. 166 167OpenSSL applies special rules for the following attribute NIDs: 168 169=over 4 170 171=item CMS Signed Attributes 172 173NID_pkcs9_contentType 174NID_pkcs9_messageDigest 175NID_pkcs9_signingTime 176 177=item ESS Signed Attributes 178 179NID_id_smime_aa_signingCertificate 180NID_id_smime_aa_signingCertificateV2 181NID_id_smime_aa_receiptRequest 182 183=item CMS Unsigned Attributes 184 185NID_pkcs9_countersignature 186 187=back 188 189CMS_signed_add1_attr(), CMS_signed_add1_attr_by_OBJ(), 190CMS_signed_add1_attr_by_NID(), CMS_signed_add1_attr_by_txt() 191and the equivalent CMS_unsigned_add1_attrXXX() functions allow 192duplicate attributes to be added. The attribute rules are not checked 193during these function calls, and are deferred until the sign or verify process 194(i.e. during calls to any of CMS_sign_ex(), CMS_sign(), CMS_sign_receipt(), 195CMS_add1_signer(), CMS_Final(), CMS_dataFinal(), CMS_final_digest(), 196CMS_verify(), CMS_verify_receipt() or CMS_SignedData_verify()). 197 198For CMS attribute rules see RFC 5652 Section 11. 199For ESS attribute rules see RFC 2634 Section 1.3.4 and RFC 5035 Section 5.4. 200 201=head1 SEE ALSO 202 203L<X509_ATTRIBUTE(3)> 204 205=head1 COPYRIGHT 206 207Copyright 2023-2024 The OpenSSL Project Authors. All Rights Reserved. 208 209Licensed under the Apache License 2.0 (the "License"). You may not use 210this file except in compliance with the License. You can obtain a copy 211in the file LICENSE in the source distribution or at 212L<https://www.openssl.org/source/license.html>. 213 214=cut 215