| blob | d2cb9baa3c1d038998f2ec1706d6b9e23b40ea0d |
1 .\" $OpenBSD: X509_NAME_ENTRY_get_object.3,v 1.12 2018/05/19 21:25:51 schwarze Exp $
2 .\" full merge up to: OpenSSL aebb9aac Jul 19 09:27:53 2016 -0400
3 .\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
4 .\"
5 .\" This file is a derived work.
6 .\" The changes are covered by the following Copyright and license:
7 .\"
8 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
9 .\"
10 .\" Permission to use, copy, modify, and distribute this software for any
11 .\" purpose with or without fee is hereby granted, provided that the above
12 .\" copyright notice and this permission notice appear in all copies.
13 .\"
14 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
15 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
16 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
17 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
18 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
19 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
20 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21 .\"
22 .\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
23 .\" Copyright (c) 2002, 2005, 2006, 2017 The OpenSSL Project.
24 .\" All rights reserved.
25 .\"
26 .\" Redistribution and use in source and binary forms, with or without
27 .\" modification, are permitted provided that the following conditions
28 .\" are met:
29 .\"
30 .\" 1. Redistributions of source code must retain the above copyright
31 .\" notice, this list of conditions and the following disclaimer.
32 .\"
33 .\" 2. Redistributions in binary form must reproduce the above copyright
34 .\" notice, this list of conditions and the following disclaimer in
35 .\" the documentation and/or other materials provided with the
36 .\" distribution.
37 .\"
38 .\" 3. All advertising materials mentioning features or use of this
39 .\" software must display the following acknowledgment:
40 .\" "This product includes software developed by the OpenSSL Project
41 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
42 .\"
43 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
44 .\" endorse or promote products derived from this software without
45 .\" prior written permission. For written permission, please contact
46 .\" openssl-core@openssl.org.
47 .\"
48 .\" 5. Products derived from this software may not be called "OpenSSL"
49 .\" nor may "OpenSSL" appear in their names without prior written
50 .\" permission of the OpenSSL Project.
51 .\"
52 .\" 6. Redistributions of any form whatsoever must retain the following
53 .\" acknowledgment:
54 .\" "This product includes software developed by the OpenSSL Project
55 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
56 .\"
57 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
58 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
59 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
60 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
61 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
62 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
63 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
64 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
65 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
66 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
67 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
68 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
69 .\"
70 .Dd $Mdocdate: May 19 2018 $
71 .Dt X509_NAME_ENTRY_GET_OBJECT 3
72 .Os
73 .Sh NAME
74 .Nm X509_NAME_ENTRY_new ,
75 .Nm X509_NAME_ENTRY_free ,
76 .Nm X509_NAME_ENTRY_get_object ,
77 .Nm X509_NAME_ENTRY_get_data ,
78 .Nm X509_NAME_ENTRY_set_object ,
79 .Nm X509_NAME_ENTRY_set_data ,
80 .Nm X509_NAME_ENTRY_create_by_txt ,
81 .Nm X509_NAME_ENTRY_create_by_NID ,
82 .Nm X509_NAME_ENTRY_create_by_OBJ
83 .\" In the following line, "X.501" is not a typo.
84 .\" This object defined in X.501, not in X.509.
85 .Nd X.501 relative distinguished name
86 .Sh SYNOPSIS
87 .In openssl/x509.h
88 .Ft X509_NAME_ENTRY *
89 .Fn X509_NAME_ENTRY_new void
90 .Ft void
91 .Fo X509_NAME_ENTRY_free
92 .Fa "X509_NAME_ENTRY* ne"
93 .Fc
94 .Ft ASN1_OBJECT *
95 .Fo X509_NAME_ENTRY_get_object
96 .Fa "const X509_NAME_ENTRY *ne"
97 .Fc
98 .Ft ASN1_STRING *
99 .Fo X509_NAME_ENTRY_get_data
100 .Fa "const X509_NAME_ENTRY *ne"
101 .Fc
102 .Ft int
103 .Fo X509_NAME_ENTRY_set_object
104 .Fa "X509_NAME_ENTRY *ne"
105 .Fa "const ASN1_OBJECT *obj"
106 .Fc
107 .Ft int
108 .Fo X509_NAME_ENTRY_set_data
109 .Fa "X509_NAME_ENTRY *ne"
110 .Fa "int type"
111 .Fa "const unsigned char *bytes"
112 .Fa "int len"
113 .Fc
114 .Ft X509_NAME_ENTRY *
115 .Fo X509_NAME_ENTRY_create_by_txt
116 .Fa "X509_NAME_ENTRY **ne"
117 .Fa "const char *field"
118 .Fa "int type"
119 .Fa "const unsigned char *bytes"
120 .Fa "int len"
121 .Fc
122 .Ft X509_NAME_ENTRY *
123 .Fo X509_NAME_ENTRY_create_by_NID
124 .Fa "X509_NAME_ENTRY **ne"
125 .Fa "int nid"
126 .Fa "int type"
127 .Fa "const unsigned char *bytes"
128 .Fa "int len"
129 .Fc
130 .Ft X509_NAME_ENTRY *
131 .Fo X509_NAME_ENTRY_create_by_OBJ
132 .Fa "X509_NAME_ENTRY **ne"
133 .Fa "const ASN1_OBJECT *obj"
134 .Fa "int type"
135 .Fa "const unsigned char *bytes"
136 .Fa "int len"
137 .Fc
138 .Sh DESCRIPTION
139 An X.501
140 .Vt RelativeDistinguishedName
141 is a set of field type and value pairs.
142 It is the building block for constructing X.501
143 .Vt Name
144 objects.
145 This implementation only supports sets with one element, so an
146 .Vt X509_NAME_ENTRY
147 object contains only one field type and one value.
148 .Pp
149 .Fn X509_NAME_ENTRY_new
150 allocates and initializes an empty
151 .Vt X509_NAME_ENTRY
152 object, representing an ASN.1
153 .Vt RelativeDistinguishedName
154 structure defined in RFC 5280 section 4.1.2.4.
155 .Pp
156 .Fn X509_NAME_ENTRY_free
157 frees
158 .Fa ne
159 and the type and value contained in it.
160 .Pp
161 .Fn X509_NAME_ENTRY_get_object
162 retrieves the field type of
163 .Fa ne
164 in an
165 .Vt ASN1_OBJECT
166 structure.
167 .Fn X509_NAME_ENTRY_get_data
168 retrieves the field value of
169 .Fa ne
170 in an
171 .Vt ASN1_STRING
172 structure.
173 These two functions can be used to examine an
174 .Vt X509_NAME_ENTRY
175 object as returned by
176 .Xr X509_NAME_get_entry 3 .
177 .Pp
178 .Fn X509_NAME_ENTRY_set_object
179 sets the field type of
180 .Fa ne
181 to
182 .Fa obj .
183 .Pp
184 .Fn X509_NAME_ENTRY_set_data
185 sets the field value of
186 .Fa ne
187 to string type
188 .Fa type
189 and the value determined by
190 .Fa bytes
191 and
192 .Fa len .
193 .Pp
194 .Fn X509_NAME_ENTRY_create_by_txt ,
195 .Fn X509_NAME_ENTRY_create_by_NID ,
196 and
197 .Fn X509_NAME_ENTRY_create_by_OBJ
198 create and return an
199 .Vt X509_NAME_ENTRY
200 structure.
201 .Pp
202 Except for
203 .Fn X509_NAME_ENTRY_get_object
204 and
205 .Fn X509_NAME_ENTRY_get_data ,
206 these functions are rarely used because
207 .Vt X509_NAME_ENTRY
208 structures are almost always part of
209 .Vt X509_NAME
210 structures and the functions described in
211 .Xr X509_NAME_add_entry_by_txt 3
212 are typically used to create and add new entries in a single operation.
213 .Pp
214 The arguments of these functions support similar options to the
215 similarly named ones described in
216 .Xr X509_NAME_add_entry_by_txt 3 .
217 So for example
218 .Fa type
219 can be set to
220 .Dv MBSTRING_ASC ,
221 but in the case of
222 .Fn X509_NAME_ENTRY_set_data
223 the field type must be set first so the relevant field information
224 can be looked up internally.
225 .Sh RETURN VALUES
226 .Fn X509_NAME_ENTRY_new ,
227 .Fn X509_NAME_ENTRY_create_by_txt ,
228 .Fn X509_NAME_ENTRY_create_by_NID ,
229 and
230 .Fn X509_NAME_ENTRY_create_by_OBJ
231 return a valid
232 .Vt X509_NAME_ENTRY
233 structure on success or
234 .Dv NULL
235 if an error occurred.
236 .Pp
237 .Fn X509_NAME_ENTRY_get_object
238 returns a valid
239 .Vt ASN1_OBJECT
240 structure if it is set or
241 .Dv NULL
242 if an error occurred.
243 .Pp
244 .Fn X509_NAME_ENTRY_get_data
245 returns a valid
246 .Vt ASN1_STRING
247 structure if it is set or
248 .Dv NULL
249 if an error occurred.
250 .Pp
251 .Fn X509_NAME_ENTRY_set_object
252 and
253 .Fn X509_NAME_ENTRY_set_data
254 return 1 on success or 0 on error.
255 .Sh SEE ALSO
256 .Xr ERR_get_error 3 ,
257 .Xr OBJ_nid2obj 3 ,
258 .Xr X509_NAME_add_entry 3 ,
259 .Xr X509_NAME_get_entry 3 ,
260 .Xr X509_NAME_new 3
261 .Sh STANDARDS
262 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
263 Certificate Revocation List (CRL) Profile
264 .Pp
265 ITU-T Recommendation X.501, also known as ISO/IEC 9594-2: Information
266 Technology Open Systems Interconnection The Directory: Models,
267 section 9.3: Relative distinguished name
268 .Sh HISTORY
269 .Fn X509_NAME_ENTRY_new
270 and
271 .Fn X509_NAME_ENTRY_free
272 first appeared in SSLeay 0.5.1.
273 .Fn X509_NAME_ENTRY_get_object ,
274 .Fn X509_NAME_ENTRY_get_data ,
275 .Fn X509_NAME_ENTRY_set_object ,
276 .Fn X509_NAME_ENTRY_set_data ,
277 .Fn X509_NAME_ENTRY_create_by_NID ,
278 and
279 .Fn X509_NAME_ENTRY_create_by_OBJ
280 first appeared in SSLeay 0.8.0.
281 These functions have been available since
282 .Ox 2.4 .
283 .Pp
284 .Fn X509_NAME_ENTRY_create_by_txt
285 first appeared in OpenSSL 0.9.5 and has been available since
286 .Ox 2.7 .