xref: /openssl/doc/man3/CMS_signed_get_attr.pod (revision b6461792) 
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