| blob | f0df3392b8eb9b525d49a97e5754820ad5213208 |
1 .\" $OpenBSD: X509_EXTENSION_set_object.3,v 1.6 2016/12/28 13:45:30 schwarze Exp $
2 .\" OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400
3 .\"
4 .\" This file is a derived work.
5 .\" The changes are covered by the following Copyright and license:
6 .\"
7 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
8 .\"
9 .\" Permission to use, copy, modify, and distribute this software for any
10 .\" purpose with or without fee is hereby granted, provided that the above
11 .\" copyright notice and this permission notice appear in all copies.
12 .\"
13 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
14 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
16 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 .\"
21 .\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
22 .\" Copyright (c) 2015 The OpenSSL Project. All rights reserved.
23 .\"
24 .\" Redistribution and use in source and binary forms, with or without
25 .\" modification, are permitted provided that the following conditions
26 .\" are met:
27 .\"
28 .\" 1. Redistributions of source code must retain the above copyright
29 .\" notice, this list of conditions and the following disclaimer.
30 .\"
31 .\" 2. Redistributions in binary form must reproduce the above copyright
32 .\" notice, this list of conditions and the following disclaimer in
33 .\" the documentation and/or other materials provided with the
34 .\" distribution.
35 .\"
36 .\" 3. All advertising materials mentioning features or use of this
37 .\" software must display the following acknowledgment:
38 .\" "This product includes software developed by the OpenSSL Project
39 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
40 .\"
41 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
42 .\" endorse or promote products derived from this software without
43 .\" prior written permission. For written permission, please contact
44 .\" openssl-core@openssl.org.
45 .\"
46 .\" 5. Products derived from this software may not be called "OpenSSL"
47 .\" nor may "OpenSSL" appear in their names without prior written
48 .\" permission of the OpenSSL Project.
49 .\"
50 .\" 6. Redistributions of any form whatsoever must retain the following
51 .\" acknowledgment:
52 .\" "This product includes software developed by the OpenSSL Project
53 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
54 .\"
55 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
56 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
57 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
58 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
59 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
60 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
61 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
62 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
63 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
64 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
65 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
66 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
67 .\"
68 .Dd $Mdocdate: December 28 2016 $
69 .Dt X509_EXTENSION_SET_OBJECT 3
70 .Os
71 .Sh NAME
72 .Nm X509_EXTENSION_new ,
73 .Nm X509_EXTENSION_free ,
74 .Nm X509_EXTENSION_create_by_NID ,
75 .Nm X509_EXTENSION_create_by_OBJ ,
76 .Nm X509_EXTENSION_set_object ,
77 .Nm X509_EXTENSION_set_critical ,
78 .Nm X509_EXTENSION_set_data ,
79 .Nm X509_EXTENSION_get_object ,
80 .Nm X509_EXTENSION_get_critical ,
81 .Nm X509_EXTENSION_get_data
82 .\" In the next line, the capital "E" is not a typo.
83 .\" The ASN.1 structure is called "Extension", not "extension".
84 .Nd create, change, and inspect X.509 Extension objects
85 .Sh SYNOPSIS
86 .In openssl/x509.h
87 .Ft X509_EXTENSION *
88 .Fn X509_EXTENSION_new void
89 .Ft void
90 .Fn X509_EXTENSION_free "X509_EXTENSION *ex"
91 .Ft X509_EXTENSION *
92 .Fo X509_EXTENSION_create_by_NID
93 .Fa "X509_EXTENSION **ex"
94 .Fa "int nid"
95 .Fa "int crit"
96 .Fa "ASN1_OCTET_STRING *data"
97 .Fc
98 .Ft X509_EXTENSION *
99 .Fo X509_EXTENSION_create_by_OBJ
100 .Fa "X509_EXTENSION **ex"
101 .Fa "ASN1_OBJECT *obj"
102 .Fa "int crit"
103 .Fa "ASN1_OCTET_STRING *data"
104 .Fc
105 .Ft int
106 .Fo X509_EXTENSION_set_object
107 .Fa "X509_EXTENSION *ex"
108 .Fa "ASN1_OBJECT *obj"
109 .Fc
110 .Ft int
111 .Fo X509_EXTENSION_set_critical
112 .Fa "X509_EXTENSION *ex"
113 .Fa "int crit"
114 .Fc
115 .Ft int
116 .Fo X509_EXTENSION_set_data
117 .Fa "X509_EXTENSION *ex"
118 .Fa "ASN1_OCTET_STRING *data"
119 .Fc
120 .Ft ASN1_OBJECT *
121 .Fo X509_EXTENSION_get_object
122 .Fa "X509_EXTENSION *ex"
123 .Fc
124 .Ft int
125 .Fo X509_EXTENSION_get_critical
126 .Fa "X509_EXTENSION *ex"
127 .Fc
128 .Ft ASN1_OCTET_STRING *
129 .Fo X509_EXTENSION_get_data
130 .Fa "X509_EXTENSION *ne"
131 .Fc
132 .Sh DESCRIPTION
133 .Fn X509_EXTENSION_new
134 allocates and initializes an empty
135 .Vt X509_EXTENSION
136 object, representing an ASN.1
137 .Vt Extension
138 structure defined in RFC 5280 section 4.1.
139 It is a wrapper object around specific extension objects of different
140 types and stores an extension type identifier and a criticality
141 flag in addition to the DER-encoded form of the wrapped object.
142 .Vt X509_EXTENSION
143 objects can be used for X.509 v3 certificates inside
144 .Vt X509_CINF
145 objects and for X.509 v2 certificate revocation lists inside
146 .Vt X509_CRL_INFO
147 and
148 .Vt X509_REVOKED
149 objects.
150 .Pp
151 .Fn X509_EXTENSION_free
152 frees
153 .Fa ex
154 and all objects it is using.
155 .Pp
156 .Fn X509_EXTENSION_create_by_NID
157 creates an extension of type
158 .Fa nid
159 and criticality
160 .Fa crit
161 using data
162 .Fa data .
163 The created extension is returned and written to
164 .Pf * Fa ex
165 reusing or allocating a new extension if necessary, so
166 .Pf * Fa ex
167 should either be
168 .Dv NULL
169 or a valid
170 .Vt X509_EXTENSION
171 structure.
172 It must not be an uninitialised pointer.
173 .Pp
174 .Fn X509_EXTENSION_create_by_OBJ
175 is identical to
176 .Fn X509_EXTENSION_create_by_NID
177 except that it creates an extension using
178 .Fa obj
179 instead of a NID.
180 .Pp
181 .Fn X509_EXTENSION_set_object
182 sets the extension type of
183 .Fa ex
184 to
185 .Fa obj .
186 The
187 .Fa obj
188 pointer is duplicated internally so
189 .Fa obj
190 should be freed up after use.
191 .Pp
192 .Fn X509_EXTENSION_set_critical
193 sets the criticality of
194 .Fa ex
195 to
196 .Fa crit .
197 If
198 .Fa crit
199 is zero, the extension in non-critical, otherwise it is critical.
200 .Pp
201 .Fn X509_EXTENSION_set_data
202 sets the data in extension
203 .Fa ex
204 to
205 .Fa data .
206 The
207 .Fa data
208 pointer is duplicated internally.
209 .Pp
210 .Fn X509_EXTENSION_get_object
211 returns the extension type of
212 .Fa ex
213 as an
214 .Vt ASN1_OBJECT
215 pointer.
216 The returned pointer is an internal value which must not be freed up.
217 .Pp
218 .Fn X509_EXTENSION_get_critical
219 returns the criticality of extension
220 .Fa ex
221 it returns 1 for critical and 0 for non-critical.
222 .Pp
223 .Fn X509_EXTENSION_get_data
224 returns the data of extension
225 .Fa ex .
226 The returned pointer is an internal value which must not be freed up.
227 .Pp
228 These functions manipulate the contents of an extension directly.
229 Most applications will want to parse or encode and add an extension:
230 they should use the extension encode and decode functions instead
231 such as
232 .Xr X509_add1_ext_i2d 3
233 and
234 .Xr X509_get_ext_d2i 3 .
235 .Pp
236 The
237 .Fa data
238 associated with an extension is the extension encoding in an
239 .Vt ASN1_OCTET_STRING
240 structure.
241 .Sh RETURN VALUES
242 .Fn X509_EXTENSION_new ,
243 .Fn X509_EXTENSION_create_by_NID ,
244 and
245 .Fn X509_EXTENSION_create_by_OBJ
246 return an
247 .Vt X509_EXTENSION
248 pointer or
249 .Dv NULL
250 if an error occurs.
251 .Pp
252 .Fn X509_EXTENSION_set_object ,
253 .Fn X509_EXTENSION_set_critical ,
254 and
255 .Fn X509_EXTENSION_set_data
256 return 1 for success or 0 for failure.
257 .Pp
258 .Fn X509_EXTENSION_get_object
259 returns an
260 .Vt ASN1_OBJECT
261 pointer.
262 .Pp
263 .Fn X509_EXTENSION_get_critical
264 returns 0 for non-critical or 1 for critical.
265 .Pp
266 .Fn X509_EXTENSION_get_data
267 returns an
268 .Vt ASN1_OCTET_STRING
269 pointer.
270 .Sh SEE ALSO
271 .Xr ACCESS_DESCRIPTION_new 3 ,
272 .Xr AUTHORITY_KEYID_new 3 ,
273 .Xr BASIC_CONSTRAINTS_new 3 ,
274 .Xr d2i_X509_EXTENSION 3 ,
275 .Xr DIST_POINT_new 3 ,
276 .Xr EXTENDED_KEY_USAGE_new 3 ,
277 .Xr NAME_CONSTRAINTS_new 3 ,
278 .Xr OCSP_CRLID_new 3 ,
279 .Xr OCSP_SERVICELOC_new 3 ,
280 .Xr PKEY_USAGE_PERIOD_new 3 ,
281 .Xr POLICYINFO_new 3 ,
282 .Xr PROXY_POLICY_new 3 ,
283 .Xr SXNET_new 3 ,
284 .Xr X509V3_get_d2i 3 ,
285 .Xr X509v3_get_ext_by_NID 3
286 .Sh STANDARDS
287 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
288 Certificate Revocation List (CRL) Profile