Debian Codegraph @

upstream/debian-unstable/man3/X509_ATTRIBUTE.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "X509_ATTRIBUTE 3SSL"
58 .TH X509_ATTRIBUTE 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 X509_ATTRIBUTE, X509at_get_attr,
65 X509at_get_attr_count, X509at_get_attr_by_NID, X509at_get_attr_by_OBJ,
66 X509at_delete_attr,
67 X509at_add1_attr,
68 X509at_add1_attr_by_OBJ, X509at_add1_attr_by_NID, X509at_add1_attr_by_txt,
69 X509at_get0_data_by_OBJ,
70 X509_ATTRIBUTE_create, X509_ATTRIBUTE_create_by_NID,
71 X509_ATTRIBUTE_create_by_OBJ, X509_ATTRIBUTE_create_by_txt,
72 X509_ATTRIBUTE_set1_object, X509_ATTRIBUTE_set1_data,
73 X509_ATTRIBUTE_count,
74 X509_ATTRIBUTE_get0_data, X509_ATTRIBUTE_get0_object, X509_ATTRIBUTE_get0_type
75 \&\- X509 attribute functions
76 .SH SYNOPSIS
77 .IX Header "SYNOPSIS"
78 .Vb 1
79 \& #include <openssl/x509.h>
80 \&
81 \& typedef struct x509_attributes_st X509_ATTRIBUTE;
82 \&
83 \& int X509at_get_attr_count(const STACK_OF(X509_ATTRIBUTE) *x);
84 \& int X509at_get_attr_by_NID(const STACK_OF(X509_ATTRIBUTE) *x, int nid,
85 \& int lastpos);
86 \& int X509at_get_attr_by_OBJ(const STACK_OF(X509_ATTRIBUTE) *sk,
87 \& const ASN1_OBJECT *obj, int lastpos);
88 \& X509_ATTRIBUTE *X509at_get_attr(const STACK_OF(X509_ATTRIBUTE) *x, int loc);
89 \& X509_ATTRIBUTE *X509at_delete_attr(STACK_OF(X509_ATTRIBUTE) *x, int loc);
90 \& STACK_OF(X509_ATTRIBUTE) *X509at_add1_attr(STACK_OF(X509_ATTRIBUTE) **x,
91 \& X509_ATTRIBUTE *attr);
92 \& STACK_OF(X509_ATTRIBUTE) *X509at_add1_attr_by_OBJ(STACK_OF(X509_ATTRIBUTE)
93 \& **x, const ASN1_OBJECT *obj,
94 \& int type,
95 \& const unsigned char *bytes,
96 \& int len);
97 \& STACK_OF(X509_ATTRIBUTE) *X509at_add1_attr_by_NID(STACK_OF(X509_ATTRIBUTE)
98 \& **x, int nid, int type,
99 \& const unsigned char *bytes,
100 \& int len);
101 \& STACK_OF(X509_ATTRIBUTE) *X509at_add1_attr_by_txt(STACK_OF(X509_ATTRIBUTE)
102 \& **x, const char *attrname,
103 \& int type,
104 \& const unsigned char *bytes,
105 \& int len);
106 \& void *X509at_get0_data_by_OBJ(const STACK_OF(X509_ATTRIBUTE) *x,
107 \& const ASN1_OBJECT *obj, int lastpos, int type);
108 \& X509_ATTRIBUTE *X509_ATTRIBUTE_create(int nid, int atrtype, void *value);
109 \& X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_NID(X509_ATTRIBUTE **attr, int nid,
110 \& int atrtype, const void *data,
111 \& int len);
112 \& X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_OBJ(X509_ATTRIBUTE **attr,
113 \& const ASN1_OBJECT *obj,
114 \& int atrtype, const void *data,
115 \& int len);
116 \& X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_txt(X509_ATTRIBUTE **attr,
117 \& const char *atrname, int type,
118 \& const unsigned char *bytes,
119 \& int len);
120 \& int X509_ATTRIBUTE_set1_object(X509_ATTRIBUTE *attr, const ASN1_OBJECT *obj);
121 \& int X509_ATTRIBUTE_set1_data(X509_ATTRIBUTE *attr, int attrtype,
122 \& const void *data, int len);
123 \& void *X509_ATTRIBUTE_get0_data(X509_ATTRIBUTE *attr, int idx, int atrtype,
124 \& void *data);
125 \& int X509_ATTRIBUTE_count(const X509_ATTRIBUTE *attr);
126 \& ASN1_OBJECT *X509_ATTRIBUTE_get0_object(X509_ATTRIBUTE *attr);
127 \& ASN1_TYPE *X509_ATTRIBUTE_get0_type(X509_ATTRIBUTE *attr, int idx);
128 .Ve
129 .SH DESCRIPTION
130 .IX Header "DESCRIPTION"
131 \&\fBX509_ATTRIBUTE\fR objects are used by many standards including X509, X509_REQ,
132 PKCS12, PKCS8, PKCS7 and CMS.
133 .PP
134 The \fBX509_ATTRIBUTE\fR object is used to represent the ASN.1 Attribute as defined
135 in RFC 5280, i.e.
136 .PP
137 .Vb 3
138 \& Attribute ::= SEQUENCE {
139 \& type AttributeType,
140 \& values SET OF AttributeValue }
141 \&
142 \& AttributeType ::= OBJECT IDENTIFIER
143 \& AttributeValue ::= ANY \-\- DEFINED BY AttributeType
144 .Ve
145 .PP
146 For example CMS defines the signing-time attribute as:
147 .PP
148 .Vb 2
149 \& id\-signingTime OBJECT IDENTIFIER ::= { iso(1) member\-body(2)
150 \& us(840) rsadsi(113549) pkcs(1) pkcs9(9) 5 }
151 \&
152 \& SigningTime ::= Time
153 \&
154 \& Time ::= CHOICE {
155 \& utcTime UTCTime,
156 \& generalizedTime GeneralizedTime }
157 .Ve
158 .PP
159 In OpenSSL \fBAttributeType\fR maps to an \fBASN1_OBJECT\fR object
160 and \fBAttributeValue\fR maps to a list of \fBASN1_TYPE\fR objects.
161 .PP
162 The following functions are used for \fBX509_ATTRIBUTE\fR objects.
163 .PP
164 \&\fBX509at_get_attr_by_OBJ()\fR finds the location of the first matching object \fIobj\fR
165 in a list of attributes \fIsk\fR. The search starts at the position after \fIlastpos\fR.
166 If the returned value is positive then it can be used on the next call to
167 \&\fBX509at_get_attr_by_OBJ()\fR as the value of \fIlastpos\fR in order to iterate through
168 the remaining attributes. \fIlastpos\fR can be set to any negative value on the
169 first call, in order to start searching from the start of the list.
170 .PP
171 \&\fBX509at_get_attr_by_NID()\fR is similar to \fBX509at_get_attr_by_OBJ()\fR except that it
172 passes the numerical identifier (NID) \fInid\fR associated with the object.
173 See <openssl/obj_mac.h> for a list of NID_*.
174 .PP
175 \&\fBX509at_get_attr()\fR returns the \fBX509_ATTRIBUTE\fR object at index \fIloc\fR in the
176 list of attributes \fIx\fR. \fIloc\fR should be in the range from 0 to
177 \&\fBX509at_get_attr_count()\fR \- 1.
178 .PP
179 \&\fBX509at_delete_attr()\fR removes the \fBX509_ATTRIBUTE\fR object at index \fIloc\fR in
180 the list of attributes \fIx\fR.
181 .PP
182 \&\fBX509at_add1_attr()\fR pushes a copy of the passed in \fBX509_ATTRIBUTE\fR object
183 to the list \fIx\fR.
184 Both \fIx\fR and \fIattr\fR must be non NULL or an error will occur.
185 If \fI*x\fR is NULL then a new list is created, otherwise it uses the
186 passed in list. An error will occur if an existing attribute (with the same
187 attribute type) already exists in the attribute list.
188 .PP
189 \&\fBX509at_add1_attr_by_OBJ()\fR creates a new \fBX509_ATTRIBUTE\fR using
190 \&\fBX509_ATTRIBUTE_set1_object()\fR and \fBX509_ATTRIBUTE_set1_data()\fR to assign a new
191 \&\fIobj\fR with type \fItype\fR and data \fIbytes\fR of length \fIlen\fR and then pushes it
192 to the attribute list \fIx\fR. Both \fIx\fR and \fIattr\fR must be non NULL or an error
193 will occur. If \fI*x\fR is NULL then a new attribute list is created. If \fIobj\fR
194 already exists in the attribute list then an error occurs.
195 .PP
196 \&\fBX509at_add1_attr_by_NID()\fR is similar to \fBX509at_add1_attr_by_OBJ()\fR except that it
197 passes the numerical identifier (NID) \fInid\fR associated with the object.
198 See <openssl/obj_mac.h> for a list of NID_*.
199 .PP
200 \&\fBX509at_add1_attr_by_txt()\fR is similar to \fBX509at_add1_attr_by_OBJ()\fR except that it
201 passes a name \fIattrname\fR associated with the object.
202 See <openssl/obj_mac.h> for a list of SN_* names.
203 .PP
204 \&\fBX509_ATTRIBUTE_set1_object()\fR assigns a \fBASN1_OBJECT\fR \fIobj\fR
205 to the attribute \fIattr\fR. If \fIattr\fR contained an existing \fBASN1_OBJECT\fR then
206 it is freed. An error occurs if either \fIattr\fR or \fIobj\fR are NULL, or if
207 the passed in \fIobj\fR cannot be duplicated.
208 .PP
209 \&\fBX509_ATTRIBUTE_set1_data()\fR pushes a new \fBASN1_TYPE\fR object onto the \fIattr\fR
210 attributes list. The new object is assigned a copy of the data in \fIdata\fR of
211 size \fIlen\fR.
212 If \fIattrtype\fR has flag \fIMBSTRING_FLAG\fR set then a table lookup using the
213 \&\fIattr\fR attributes NID is used to set an \fBASN1_STRING\fR using
214 \&\fBASN1_STRING_set_by_NID()\fR, and the passed in \fIdata\fR must be in the format
215 required for that object type or an error will occur.
216 If \fIlen\fR is not \-1 then internally \fBASN1_STRING_type_new()\fR is
217 used with the passed in \fIattrtype\fR.
218 If \fIattrtype\fR is 0 the call does nothing except return 1.
219 .PP
220 \&\fBX509_ATTRIBUTE_create()\fR creates a new \fBX509_ATTRIBUTE\fR using the \fInid\fR
221 to set the \fBASN1_OBJECT\fR OID and the \fIatrtype\fR and \fIvalue\fR to set the
222 \&\fBASN1_TYPE\fR.
223 .PP
224 \&\fBX509_ATTRIBUTE_create_by_OBJ()\fR uses \fBX509_ATTRIBUTE_set1_object()\fR and
225 \&\fBX509_ATTRIBUTE_set1_data()\fR to assign a new \fIobj\fR with type \fIatrtype\fR and
226 data \fIdata\fR of length \fIlen\fR. If the passed in attribute \fIattr\fR OR \fI*attr\fR is
227 NULL then a new \fBX509_ATTRIBUTE\fR will be returned, otherwise the passed in
228 \&\fBX509_ATTRIBUTE\fR is used. Note that the ASN1_OBJECT \fIobj\fR is pushed onto the
229 attributes existing list of objects, which could be an issue if the attributes
230 <ASN1_OBJECT> was different.
231 .PP
232 \&\fBX509_ATTRIBUTE_create_by_NID()\fR is similar to \fBX509_ATTRIBUTE_create_by_OBJ()\fR
233 except that it passes the numerical identifier (NID) \fInid\fR associated with the
234 object. See <openssl/obj_mac.h> for a list of NID_*.
235 .PP
236 \&\fBX509_ATTRIBUTE_create_by_txt()\fR is similar to \fBX509_ATTRIBUTE_create_by_OBJ()\fR
237 except that it passes a name \fIatrname\fR associated with the
238 object. See <openssl/obj_mac.h> for a list of SN_* names.
239 .PP
240 \&\fBX509_ATTRIBUTE_count()\fR returns the number of \fBASN1_TYPE\fR objects in an
241 attribute \fIattr\fR.
242 .PP
243 \&\fBX509_ATTRIBUTE_get0_type()\fR returns the \fBASN1_TYPE\fR object at index \fIidx\fR in
244 the attribute list \fIattr\fR. \fIidx\fR should be in the
245 range of 0 to \fBX509_ATTRIBUTE_count()\fR \- 1 or an error will occur.
246 .PP
247 \&\fBX509_ATTRIBUTE_get0_data()\fR returns the data of an \fBASN1_TYPE\fR object at
248 index \fIidx\fR in the attribute \fIattr\fR. \fIdata\fR is unused and can be set to NULL.
249 An error will occur if the attribute type \fIatrtype\fR does not match the type of
250 the \fBASN1_TYPE\fR object at index \fIidx\fR OR if \fIatrtype\fR is either
251 \&\fBV_ASN1_BOOLEAN\fR or \fBV_ASN1_NULL\fR OR if the \fIidx\fR is not in the
252 range 0 to \fBX509_ATTRIBUTE_count()\fR \- 1.
253 .PP
254 \&\fBX509at_get0_data_by_OBJ()\fR finds the first attribute in an attribute list \fIx\fR
255 that matches the \fIobj\fR starting at index \fIlastpos\fR and returns the data
256 retrieved from the found attributes first \fBASN1_TYPE\fR object. An error will
257 occur if the attribute type \fItype\fR does not match the type of the \fBASN1_TYPE\fR
258 object OR if \fItype\fR is either \fBV_ASN1_BOOLEAN\fR or \fBV_ASN1_NULL\fR OR the
259 attribute is not found.
260 If \fIlastpos\fR is less than \-1 then an error will occur if there are multiple
261 objects in the list \fIx\fR that match \fIobj\fR.
262 If \fIlastpos\fR is less than \-2 then an error will occur if there is more than
263 one \fBASN1_TYPE\fR object in the found attribute.
264 .SH "RETURN VALUES"
265 .IX Header "RETURN VALUES"
266 \&\fBX509at_get_attr_count()\fR returns the number of attributes in the list \fIx\fR or \-1
267 if \fIx\fR is NULL.
268 .PP
269 \&\fBX509at_get_attr_by_OBJ()\fR returns \-1 if either the list is empty OR the object
270 is not found, otherwise it returns the location of the object in the list.
271 .PP
272 \&\fBX509at_get_attr_by_NID()\fR is similar to \fBX509at_get_attr_by_OBJ()\fR, except that
273 it returns \-2 if the \fInid\fR is not known by OpenSSL.
274 .PP
275 \&\fBX509at_get_attr()\fR returns either an \fBX509_ATTRIBUTE\fR or NULL if there is a error.
276 .PP
277 \&\fBX509at_delete_attr()\fR returns either the removed \fBX509_ATTRIBUTE\fR or NULL if
278 there is a error.
279 .PP
280 \&\fBX509_ATTRIBUTE_count()\fR returns \-1 on error, otherwise it returns the number
281 of \fBASN1_TYPE\fR elements.
282 .PP
283 \&\fBX509_ATTRIBUTE_get0_type()\fR returns NULL on error, otherwise it returns a
284 \&\fBASN1_TYPE\fR object.
285 .PP
286 \&\fBX509_ATTRIBUTE_get0_data()\fR returns NULL if an error occurs,
287 otherwise it returns the data associated with an \fBASN1_TYPE\fR object.
288 .PP
289 \&\fBX509_ATTRIBUTE_set1_object()\fR and \fBX509_ATTRIBUTE_set1_data()\fR returns 1 on
290 success, or 0 otherwise.
291 .PP
292 \&\fBX509_ATTRIBUTE_create()\fR, \fBX509_ATTRIBUTE_create_by_OBJ()\fR,
293 \&\fBX509_ATTRIBUTE_create_by_NID()\fR and \fBX509_ATTRIBUTE_create_by_txt()\fR return either
294 a \fBX509_ATTRIBUTE\fR on success, or NULL if there is a error.
295 .PP
296 \&\fBX509at_add1_attr()\fR, \fBX509at_add1_attr_by_OBJ()\fR, \fBX509at_add1_attr_by_NID()\fR and
297 \&\fBX509at_add1_attr_by_txt()\fR return NULL on error, otherwise they return a list
298 of \fBX509_ATTRIBUTE\fR.
299 .PP
300 \&\fBX509at_get0_data_by_OBJ()\fR returns the data retrieved from the found attributes
301 first \fBASN1_TYPE\fR object, or NULL if an error occurs.
302 .SH "SEE ALSO"
303 .IX Header "SEE ALSO"
304 \&\fBASN1_TYPE_get\fR\|(3),
305 \&\fBASN1_INTEGER_get\fR\|(3),
306 \&\fBASN1_ENUMERATED_get\fR\|(3),
307 \&\fBASN1_STRING_get0_data\fR\|(3),
308 \&\fBASN1_STRING_length\fR\|(3),
309 \&\fBASN1_STRING_type\fR\|(3),
310 \&\fBX509_REQ_get_attr\fR\|(3),
311 \&\fBEVP_PKEY_get_attr\fR\|(3),
312 \&\fBCMS_signed_get_attr\fR\|(3),
313 \&\fBPKCS8_pkey_get0_attrs\fR\|(3),
314 .SH COPYRIGHT
315 .IX Header "COPYRIGHT"
316 Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved.
317 .PP
318 Licensed under the Apache License 2.0 (the "License"). You may not use
319 this file except in compliance with the License. You can obtain a copy
320 in the file LICENSE in the source distribution or at
321 <https://www.openssl.org/source/license.html>.