summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/OBJ_nid2obj.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/OBJ_nid2obj.3')
-rw-r--r--src/lib/libcrypto/man/OBJ_nid2obj.3479
1 files changed, 0 insertions, 479 deletions
diff --git a/src/lib/libcrypto/man/OBJ_nid2obj.3 b/src/lib/libcrypto/man/OBJ_nid2obj.3
deleted file mode 100644
index db9cd05c26..0000000000
--- a/src/lib/libcrypto/man/OBJ_nid2obj.3
+++ /dev/null
@@ -1,479 +0,0 @@
1.\" $OpenBSD: OBJ_nid2obj.3,v 1.15 2021/07/05 17:57:16 schwarze Exp $
2.\" OpenSSL c264592d May 14 11:28:00 2006 +0000
3.\"
4.\" This file is a derived work.
5.\" The changes are covered by the following Copyright and license:
6.\"
7.\" Copyright (c) 2017, 2021 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) 2002, 2006, 2015, 2016 The OpenSSL Project.
23.\" All rights reserved.
24.\"
25.\" Redistribution and use in source and binary forms, with or without
26.\" modification, are permitted provided that the following conditions
27.\" are met:
28.\"
29.\" 1. Redistributions of source code must retain the above copyright
30.\" notice, this list of conditions and the following disclaimer.
31.\"
32.\" 2. Redistributions in binary form must reproduce the above copyright
33.\" notice, this list of conditions and the following disclaimer in
34.\" the documentation and/or other materials provided with the
35.\" distribution.
36.\"
37.\" 3. All advertising materials mentioning features or use of this
38.\" software must display the following acknowledgment:
39.\" "This product includes software developed by the OpenSSL Project
40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
41.\"
42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
43.\" endorse or promote products derived from this software without
44.\" prior written permission. For written permission, please contact
45.\" openssl-core@openssl.org.
46.\"
47.\" 5. Products derived from this software may not be called "OpenSSL"
48.\" nor may "OpenSSL" appear in their names without prior written
49.\" permission of the OpenSSL Project.
50.\"
51.\" 6. Redistributions of any form whatsoever must retain the following
52.\" acknowledgment:
53.\" "This product includes software developed by the OpenSSL Project
54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
55.\"
56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
67.\" OF THE POSSIBILITY OF SUCH DAMAGE.
68.\"
69.Dd $Mdocdate: July 5 2021 $
70.Dt OBJ_NID2OBJ 3
71.Os
72.Sh NAME
73.Nm OBJ_nid2obj ,
74.Nm OBJ_nid2ln ,
75.Nm OBJ_nid2sn ,
76.Nm OBJ_obj2nid ,
77.Nm OBJ_ln2nid ,
78.Nm OBJ_sn2nid ,
79.Nm OBJ_txt2nid ,
80.Nm OBJ_txt2obj ,
81.Nm OBJ_obj2txt ,
82.Nm OBJ_cmp ,
83.Nm OBJ_dup ,
84.Nm OBJ_create ,
85.Nm OBJ_cleanup ,
86.Nm i2t_ASN1_OBJECT ,
87.Nm i2a_ASN1_OBJECT
88.Nd inspect and create ASN.1 object identifiers
89.Sh SYNOPSIS
90.In openssl/objects.h
91.Ft ASN1_OBJECT *
92.Fo OBJ_nid2obj
93.Fa "int n"
94.Fc
95.Ft const char *
96.Fo OBJ_nid2ln
97.Fa "int n"
98.Fc
99.Ft const char *
100.Fo OBJ_nid2sn
101.Fa "int n"
102.Fc
103.Ft int
104.Fo OBJ_obj2nid
105.Fa "const ASN1_OBJECT *o"
106.Fc
107.Ft int
108.Fo OBJ_ln2nid
109.Fa "const char *ln"
110.Fc
111.Ft int
112.Fo OBJ_sn2nid
113.Fa "const char *sn"
114.Fc
115.Ft int
116.Fo OBJ_txt2nid
117.Fa "const char *s"
118.Fc
119.Ft ASN1_OBJECT *
120.Fo OBJ_txt2obj
121.Fa "const char *s"
122.Fa "int no_name"
123.Fc
124.Ft int
125.Fo OBJ_obj2txt
126.Fa "char *buf"
127.Fa "int buf_len"
128.Fa "const ASN1_OBJECT *a"
129.Fa "int no_name"
130.Fc
131.Ft int
132.Fo OBJ_cmp
133.Fa "const ASN1_OBJECT *a"
134.Fa "const ASN1_OBJECT *b"
135.Fc
136.Ft ASN1_OBJECT *
137.Fo OBJ_dup
138.Fa "const ASN1_OBJECT *o"
139.Fc
140.Ft int
141.Fo OBJ_create
142.Fa "const char *oid"
143.Fa "const char *sn"
144.Fa "const char *ln"
145.Fc
146.Ft void
147.Fn OBJ_cleanup void
148.In openssl/asn1.h
149.Ft int
150.Fo i2t_ASN1_OBJECT
151.Fa "char *buf"
152.Fa "int buf_len"
153.Fa "const ASN1_OBJECT *a"
154.Fc
155.Ft int
156.Fo i2a_ASN1_OBJECT
157.Fa "BIO *out_bio"
158.Fa "const ASN1_OBJECT *a"
159.Fc
160.Sh DESCRIPTION
161The ASN.1 object utility functions process
162.Vt ASN1_OBJECT
163structures which are a representation of the ASN.1 OBJECT IDENTIFIER
164(OID) type.
165For convenience, OIDs are usually represented in source code as
166numeric identifiers, or NIDs.
167OpenSSL has an internal table of OIDs that are generated when the
168library is built, and their corresponding NIDs are available as
169defined constants.
170For the functions below, application code should treat all returned
171values \(em OIDs, NIDs, or names \(em as constants.
172.Pp
173.Fn OBJ_nid2obj ,
174.Fn OBJ_nid2ln ,
175and
176.Fn OBJ_nid2sn
177convert the NID
178.Fa n
179to an
180.Vt ASN1_OBJECT
181structure, its long name, and its short name, respectively, or return
182.Dv NULL
183if an error occurred.
184.Pp
185.Fn OBJ_obj2nid ,
186.Fn OBJ_ln2nid ,
187and
188.Fn OBJ_sn2nid
189return the corresponding NID for the object
190.Fa o ,
191the long name
192.Fa ln ,
193or the short name
194.Fa sn ,
195respectively, or
196.Dv NID_undef
197if an error occurred.
198.Pp
199.Fn OBJ_txt2nid
200returns the NID corresponding to text string
201.Fa s .
202.Fa s
203can be a long name, a short name, or the numerical representation
204of an object.
205.Pp
206.Fn OBJ_txt2obj
207converts the text string
208.Fa s
209into an
210.Vt ASN1_OBJECT
211structure.
212If
213.Fa no_name
214is 0 then long names and short names will be interpreted as well as
215numerical forms.
216If
217.Fa no_name
218is 1 only the numerical form is acceptable.
219.Pp
220.Fn OBJ_obj2txt
221converts the
222.Vt ASN1_OBJECT
223.Fa a
224into a textual representation.
225The representation is written as a NUL terminated string to
226.Fa buf .
227At most
228.Fa buf_len
229bytes are written, truncating the result if necessary.
230The total amount of space required is returned.
231If
232.Fa no_name
233is 0 and the object has a long or short name, then that will be used,
234otherwise the numerical form will be used.
235.Pp
236.Fn i2t_ASN1_OBJECT
237is the same as
238.Fn OBJ_obj2txt
239with
240.Fa no_name
241set to 0.
242.Pp
243.Fn i2a_ASN1_OBJECT
244writes a textual representation of
245.Fa a
246to
247.Fa out_bio
248using
249.Xr BIO_write 3 .
250It does not write a terminating NUL byte.
251If
252.Fa a
253is
254.Dv NULL
255or contains no data, it writes the 4-byte string
256.Qq NULL .
257If
258.Fn i2t_ASN1_OBJECT
259fails,
260.Fn i2a_ASN1_OBJECT
261writes the 9-byte string
262.Qq <INVALID> .
263Otherwise, it writes the string constructed with
264.Fn i2t_ASN1_OBJECT .
265.Pp
266.Fn OBJ_cmp
267compares
268.Fa a
269to
270.Fa b .
271If the two are identical, 0 is returned.
272.Pp
273.Fn OBJ_dup
274returns a deep copy of
275.Fa o
276if
277.Fa o
278is marked as dynamically allocated.
279The new object and all data contained in it is marked as dynamically
280allocated.
281If
282.Fa o
283is not marked as dynamically allocated,
284.Fn OBJ_dup
285just returns
286.Fa o
287itself.
288.Pp
289.Fn OBJ_create
290adds a new object to the internal table.
291.Fa oid
292is the numerical form of the object,
293.Fa sn
294the short name and
295.Fa ln
296the long name.
297A new NID is returned for the created object.
298.Pp
299The new object added to the internal table and all the data
300contained in it is marked as not dynamically allocated.
301Consequently, retrieving it with
302.Fn OBJ_nid2obj
303or a similar function and then calling
304.Xr ASN1_OBJECT_free 3
305on the returned pointer will have no effect.
306.Pp
307.Fn OBJ_cleanup
308cleans up the internal object table: this should be called before
309an application exits if any new objects were added using
310.Fn OBJ_create .
311.Pp
312Objects can have a short name, a long name, and a numerical
313identifier (NID) associated with them.
314A standard set of objects is represented in an internal table.
315The appropriate values are defined in the header file
316.In openssl/objects.h .
317.Pp
318For example, the OID for commonName has the following definitions:
319.Bd -literal
320#define SN_commonName "CN"
321#define LN_commonName "commonName"
322#define NID_commonName 13
323.Ed
324.Pp
325New objects can be added by calling
326.Fn OBJ_create .
327.Pp
328Table objects have certain advantages over other objects: for example
329their NIDs can be used in a C language switch statement.
330They are also static constant structures which are shared: that is there
331is only a single constant structure for each table object.
332.Pp
333Objects which are not in the table have the NID value
334.Dv NID_undef .
335.Pp
336Objects do not need to be in the internal tables to be processed:
337the functions
338.Fn OBJ_txt2obj
339and
340.Fn OBJ_obj2txt
341can process the numerical form of an OID.
342.Sh RETURN VALUES
343.Fn OBJ_nid2obj ,
344.Fn OBJ_txt2obj ,
345and
346.Fn OBJ_dup
347return an
348.Vt ASN1_OBJECT
349object or
350.Dv NULL
351if an error occurs.
352.Pp
353.Fn OBJ_nid2ln
354and
355.Fn OBJ_nid2sn
356return a valid string or
357.Dv NULL
358on error.
359.Pp
360.Fn OBJ_obj2nid ,
361.Fn OBJ_ln2nid ,
362.Fn OBJ_sn2nid ,
363and
364.Fn OBJ_txt2nid
365return a NID or
366.Dv NID_undef
367on error.
368.Pp
369.Fn OBJ_obj2txt
370and
371.Fn i2t_ASN1_OBJECT
372return the amount of space required in bytes,
373including the terminating NUL byte.
374.Pp
375.Fn i2a_ASN1_OBJECT
376returns the number of bytes written, even if
377.Fa a
378is invalid or contains invalid data,
379but a negative value if memory allocation or a write operation fails.
380.Pp
381.Fn OBJ_cmp
382returns 0 if the contents of
383.Fa a
384and
385.Fa b
386are identical, or non-zero otherwise.
387.Pp
388.Fn OBJ_create
389returns the new NID or
390.Dv NID_undef
391if an error occurs.
392.Pp
393In some cases of failure of
394.Fn OBJ_nid2obj ,
395.Fn OBJ_nid2ln ,
396.Fn OBJ_nid2sn ,
397.Fn OBJ_txt2nid ,
398.Fn OBJ_txt2obj ,
399.Fn OBJ_obj2txt ,
400.Fn OBJ_dup ,
401.Fn OBJ_create ,
402.Fn i2t_ASN1_OBJECT ,
403and
404.Fn i2a_ASN1_OBJECT ,
405the reason can be determined with
406.Xr ERR_get_error 3 .
407.Sh EXAMPLES
408Create an object for
409.Sy commonName :
410.Bd -literal -offset indent
411ASN1_OBJECT *o;
412o = OBJ_nid2obj(NID_commonName);
413.Ed
414.Pp
415Check if an object is
416.Sy commonName :
417.Bd -literal -offset indent
418if (OBJ_obj2nid(obj) == NID_commonName)
419 /* Do something */
420.Ed
421.Pp
422Create a new NID and initialize an object from it:
423.Bd -literal -offset indent
424int new_nid;
425ASN1_OBJECT *obj;
426new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
427obj = OBJ_nid2obj(new_nid);
428.Ed
429.Pp
430Create a new object directly:
431.Bd -literal -offset indent
432obj = OBJ_txt2obj("1.2.3.4", 1);
433.Ed
434.Sh SEE ALSO
435.Xr ASN1_OBJECT_new 3 ,
436.Xr BIO_new 3 ,
437.Xr d2i_ASN1_OBJECT 3
438.Sh HISTORY
439.Fn OBJ_nid2obj ,
440.Fn OBJ_nid2ln ,
441.Fn OBJ_nid2sn ,
442.Fn OBJ_obj2nid ,
443.Fn OBJ_ln2nid ,
444.Fn OBJ_sn2nid ,
445.Fn OBJ_txt2nid ,
446.Fn OBJ_cmp ,
447and
448.Fn OBJ_dup
449first appeared in SSLeay 0.5.1.
450.Fn i2a_ASN1_OBJECT
451first appeared in SSLeay 0.6.0,
452.Fn OBJ_cleanup
453in SSLeay 0.8.0, and
454.Fn OBJ_create
455and
456.Fn i2t_ASN1_OBJECT
457in SSLeay 0.9.0.
458All these functions have been available since
459.Ox 2.4 .
460.Pp
461.Fn OBJ_txt2obj
462first appeared in OpenSSL 0.9.2b.
463.Fn OBJ_obj2txt
464first appeared in OpenSSL 0.9.4.
465Both functions have been available since
466.Ox 2.6 .
467.Sh BUGS
468.Fn OBJ_obj2txt
469is awkward and messy to use: it doesn't follow the convention of other
470OpenSSL functions where the buffer can be set to
471.Dv NULL
472to determine the amount of data that should be written.
473Instead
474.Fa buf
475must point to a valid buffer and
476.Fa buf_len
477should be set to a positive value.
478A buffer length of 80 should be more than enough to handle any OID
479encountered in practice.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-02-13 22:41:38 +0000