summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/X509_NAME_ENTRY_get_object.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/X509_NAME_ENTRY_get_object.3')
-rw-r--r--src/lib/libcrypto/man/X509_NAME_ENTRY_get_object.3369
1 files changed, 0 insertions, 369 deletions
diff --git a/src/lib/libcrypto/man/X509_NAME_ENTRY_get_object.3 b/src/lib/libcrypto/man/X509_NAME_ENTRY_get_object.3
deleted file mode 100644
index 7437ee82c1..0000000000
--- a/src/lib/libcrypto/man/X509_NAME_ENTRY_get_object.3
+++ /dev/null
@@ -1,369 +0,0 @@
1.\" $OpenBSD: X509_NAME_ENTRY_get_object.3,v 1.14 2021/07/02 16:13:56 schwarze Exp $
2.\" full merge up to: OpenSSL aebb9aac Jul 19 09:27:53 2016 -0400
3.\" selective merge up to: OpenSSL ca34e08d Dec 12 07:38:07 2018 +0100
4.\"
5.\" This file is a derived work.
6.\" The changes are covered by the following Copyright and license:
7.\"
8.\" Copyright (c) 2016, 2018, 2019, 2021 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: July 2 2021 $
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 ,
79.Nm X509_NAME_ENTRY_set_object ,
80.Nm X509_NAME_ENTRY_set_data ,
81.Nm X509_NAME_ENTRY_create_by_txt ,
82.Nm X509_NAME_ENTRY_create_by_NID ,
83.Nm X509_NAME_ENTRY_create_by_OBJ
84.\" In the following line, "X.501" is not a typo.
85.\" This object defined in X.501, not in X.509.
86.Nd X.501 relative distinguished name
87.Sh SYNOPSIS
88.In openssl/x509.h
89.Ft X509_NAME_ENTRY *
90.Fn X509_NAME_ENTRY_new void
91.Ft void
92.Fo X509_NAME_ENTRY_free
93.Fa "X509_NAME_ENTRY* ne"
94.Fc
95.Ft ASN1_OBJECT *
96.Fo X509_NAME_ENTRY_get_object
97.Fa "const X509_NAME_ENTRY *ne"
98.Fc
99.Ft ASN1_STRING *
100.Fo X509_NAME_ENTRY_get_data
101.Fa "const X509_NAME_ENTRY *ne"
102.Fc
103.Ft int
104.Fo X509_NAME_ENTRY_set
105.Fa "const X509_NAME_ENTRY *ne"
106.Fc
107.Ft int
108.Fo X509_NAME_ENTRY_set_object
109.Fa "X509_NAME_ENTRY *ne"
110.Fa "const ASN1_OBJECT *obj"
111.Fc
112.Ft int
113.Fo X509_NAME_ENTRY_set_data
114.Fa "X509_NAME_ENTRY *ne"
115.Fa "int type"
116.Fa "const unsigned char *bytes"
117.Fa "int len"
118.Fc
119.Ft X509_NAME_ENTRY *
120.Fo X509_NAME_ENTRY_create_by_txt
121.Fa "X509_NAME_ENTRY **ne"
122.Fa "const char *field"
123.Fa "int type"
124.Fa "const unsigned char *bytes"
125.Fa "int len"
126.Fc
127.Ft X509_NAME_ENTRY *
128.Fo X509_NAME_ENTRY_create_by_NID
129.Fa "X509_NAME_ENTRY **ne"
130.Fa "int nid"
131.Fa "int type"
132.Fa "const unsigned char *bytes"
133.Fa "int len"
134.Fc
135.Ft X509_NAME_ENTRY *
136.Fo X509_NAME_ENTRY_create_by_OBJ
137.Fa "X509_NAME_ENTRY **ne"
138.Fa "const ASN1_OBJECT *obj"
139.Fa "int type"
140.Fa "const unsigned char *bytes"
141.Fa "int len"
142.Fc
143.Sh DESCRIPTION
144An X.501
145.Vt RelativeDistinguishedName
146is an ordered set of field type and value pairs.
147It is the building block for constructing X.501
148.Vt Name
149objects.
150The
151.Vt X509_NAME_ENTRY
152object stores one such pair, containing one field type and one value.
153.Pp
154.Vt X509_NAME_ENTRY
155objects are intended for use by the
156.Vt X509_NAME
157objects documented in
158.Xr X509_NAME_new 3 .
159Since part of the information about how several
160.Vt X509_NAME_ENTRY
161objects combine to form an X.501
162.Vt Name
163is stored in the individual
164.Vt X509_NAME_ENTRY
165objects rather than in the
166.Vt X509_NAME
167object, any given
168.Vt X509_NAME_ENTRY
169object can only be used by one
170.Vt X509_NAME
171object at a time.
172.Pp
173.Fn X509_NAME_ENTRY_new
174allocates and initializes an empty
175.Vt X509_NAME_ENTRY
176object, representing an ASN.1
177.Vt RelativeDistinguishedName
178structure defined in RFC 5280 section 4.1.2.4, but containing not more
179than one type-value-pair.
180.Pp
181.Fn X509_NAME_ENTRY_free
182frees
183.Fa ne
184and the type and value contained in it.
185.Pp
186.Fn X509_NAME_ENTRY_get_object
187retrieves the field type of
188.Fa ne
189in an
190.Vt ASN1_OBJECT
191structure.
192.Fn X509_NAME_ENTRY_get_data
193retrieves the field value of
194.Fa ne
195in an
196.Vt ASN1_STRING
197structure.
198These two functions can be used to examine an
199.Vt X509_NAME_ENTRY
200object as returned by
201.Xr X509_NAME_get_entry 3 .
202.Pp
203.Fn X509_NAME_ENTRY_set
204retrieves the index of the X.501
205.Vt RelativeDistinguishedName Pq RDN
206that
207.Fa ne
208is part of in the X.501
209.Vt Name
210object using it.
211The first RDN has index 0.
212If an RDN consists of more than one
213.Vt X509_NAME_ENTRY
214object, they all share the same index.
215In practice, RDNs containing more than one type-value-pair are rarely
216used, so if an
217.Va X509_NAME *name
218object uses
219.Fa ne ,
220then
221.Fn X509_NAME_ENTRY_set ne
222usually agrees with
223.Fn sk_X509_NAME_ENTRY_find name->entries ne ,
224but when multi-pair RDNs are used, it may be smaller.
225.Pp
226.Fn X509_NAME_ENTRY_set_object
227sets the field type of
228.Fa ne
229to
230.Fa obj .
231.Pp
232.Fn X509_NAME_ENTRY_set_data
233sets the field value of
234.Fa ne
235to string type
236.Fa type
237and the value determined by
238.Fa bytes
239and
240.Fa len .
241.Pp
242.Fn X509_NAME_ENTRY_create_by_txt ,
243.Fn X509_NAME_ENTRY_create_by_NID ,
244and
245.Fn X509_NAME_ENTRY_create_by_OBJ
246create and return an
247.Vt X509_NAME_ENTRY
248structure.
249.Pp
250Except for
251.Fn X509_NAME_ENTRY_get_object
252and
253.Fn X509_NAME_ENTRY_get_data ,
254these functions are rarely used because
255.Vt X509_NAME_ENTRY
256structures are almost always part of
257.Vt X509_NAME
258structures and the functions described in
259.Xr X509_NAME_add_entry_by_txt 3
260are typically used to create and add new entries in a single operation.
261.Pp
262The arguments of these functions support similar options to the
263similarly named ones described in
264.Xr X509_NAME_add_entry_by_txt 3 .
265So for example
266.Fa type
267can be set to
268.Dv MBSTRING_ASC ,
269but in the case of
270.Fn X509_NAME_ENTRY_set_data
271the field type must be set first so the relevant field information
272can be looked up internally.
273.Sh RETURN VALUES
274The
275.Fn X509_NAME_ENTRY_new
276function returns a valid
277.Vt X509_NAME_ENTRY
278structure if successful; otherwise
279.Dv NULL
280is returned and an error code can be retrieved with
281.Xr ERR_get_error 3 .
282.Pp
283.Fn X509_NAME_ENTRY_get_object
284returns a valid
285.Vt ASN1_OBJECT
286structure if it is set or
287.Dv NULL
288if an error occurred.
289.Pp
290.Fn X509_NAME_ENTRY_get_data
291returns a valid
292.Vt ASN1_STRING
293structure if it is set or
294.Dv NULL
295if an error occurred.
296.Pp
297.Fn X509_NAME_ENTRY_set
298returns the zero-based index of the RDN
299.Fa ne
300is used in, or 0 if
301.Fa ne
302is not yet used by any
303.Vt X509_NAME
304object.
305.Pp
306The
307.Fn X509_NAME_ENTRY_set_object
308function returns 1 if successful;
309otherwise 0 is returned and an error code can be retrieved with
310.Xr ERR_get_error 3 .
311.Pp
312.Fn X509_NAME_ENTRY_set_data
313returns 1 on success or 0 on error.
314In some cases of failure, the reason can be determined with
315.Xr ERR_get_error 3 .
316.Pp
317.Fn X509_NAME_ENTRY_create_by_txt ,
318.Fn X509_NAME_ENTRY_create_by_NID ,
319and
320.Fn X509_NAME_ENTRY_create_by_OBJ
321return a valid
322.Vt X509_NAME_ENTRY
323structure on success or
324.Dv NULL
325if an error occurred.
326In some cases of failure, the reason can be determined with
327.Xr ERR_get_error 3 .
328.Sh SEE ALSO
329.Xr OBJ_nid2obj 3 ,
330.Xr X509_NAME_add_entry 3 ,
331.Xr X509_NAME_get_entry 3 ,
332.Xr X509_NAME_new 3
333.Sh STANDARDS
334RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
335Certificate Revocation List (CRL) Profile
336.Pp
337ITU-T Recommendation X.501, also known as ISO/IEC 9594-2: Information
338Technology Open Systems Interconnection The Directory: Models,
339section 9.3: Relative distinguished name
340.Sh HISTORY
341.Fn X509_NAME_ENTRY_new
342and
343.Fn X509_NAME_ENTRY_free
344first appeared in SSLeay 0.5.1.
345.Fn X509_NAME_ENTRY_get_object ,
346.Fn X509_NAME_ENTRY_get_data ,
347.Fn X509_NAME_ENTRY_set_object ,
348.Fn X509_NAME_ENTRY_set_data ,
349.Fn X509_NAME_ENTRY_create_by_NID ,
350and
351.Fn X509_NAME_ENTRY_create_by_OBJ
352first appeared in SSLeay 0.8.0.
353These functions have been available since
354.Ox 2.4 .
355.Pp
356.Fn X509_NAME_ENTRY_create_by_txt
357first appeared in OpenSSL 0.9.5 and has been available since
358.Ox 2.7 .
359.Pp
360.Fn X509_NAME_ENTRY_set
361first appeared in OpenSSL 1.1.0 and has been available since
362.Ox 6.3 .
363.Sh CAVEATS
364Despite its name,
365.Fn X509_NAME_ENTRY_set
366does not set anything.
367Something like
368.Dq X509_NAME_ENTRY_get_set
369would have been a better name.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-02-13 20:48:39 +0000