1.\" $OpenBSD: OBJ_nid2obj.3,v 1.14 2019/06/14 13:59:32 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 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: June 14 2019 $ 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.Nd inspect and create ASN.1 object identifiers 88.Sh SYNOPSIS 89.In openssl/objects.h 90.Ft ASN1_OBJECT * 91.Fo OBJ_nid2obj 92.Fa "int n" 93.Fc 94.Ft const char * 95.Fo OBJ_nid2ln 96.Fa "int n" 97.Fc 98.Ft const char * 99.Fo OBJ_nid2sn 100.Fa "int n" 101.Fc 102.Ft int 103.Fo OBJ_obj2nid 104.Fa "const ASN1_OBJECT *o" 105.Fc 106.Ft int 107.Fo OBJ_ln2nid 108.Fa "const char *ln" 109.Fc 110.Ft int 111.Fo OBJ_sn2nid 112.Fa "const char *sn" 113.Fc 114.Ft int 115.Fo OBJ_txt2nid 116.Fa "const char *s" 117.Fc 118.Ft ASN1_OBJECT * 119.Fo OBJ_txt2obj 120.Fa "const char *s" 121.Fa "int no_name" 122.Fc 123.Ft int 124.Fo OBJ_obj2txt 125.Fa "char *buf" 126.Fa "int buf_len" 127.Fa "const ASN1_OBJECT *a" 128.Fa "int no_name" 129.Fc 130.Ft int 131.Fo OBJ_cmp 132.Fa "const ASN1_OBJECT *a" 133.Fa "const ASN1_OBJECT *b" 134.Fc 135.Ft ASN1_OBJECT * 136.Fo OBJ_dup 137.Fa "const ASN1_OBJECT *o" 138.Fc 139.Ft int 140.Fo OBJ_create 141.Fa "const char *oid" 142.Fa "const char *sn" 143.Fa "const char *ln" 144.Fc 145.Ft void 146.Fn OBJ_cleanup void 147.In openssl/asn1.h 148.Ft int 149.Fo i2t_ASN1_OBJECT 150.Fa "char *buf" 151.Fa "int buf_len" 152.Fa "const ASN1_OBJECT *a" 153.Fc 154.Sh DESCRIPTION 155The ASN.1 object utility functions process 156.Vt ASN1_OBJECT 157structures which are a representation of the ASN.1 OBJECT IDENTIFIER 158(OID) type. 159For convenience, OIDs are usually represented in source code as 160numeric identifiers, or NIDs. 161OpenSSL has an internal table of OIDs that are generated when the 162library is built, and their corresponding NIDs are available as 163defined constants. 164For the functions below, application code should treat all returned 165values \(em OIDs, NIDs, or names \(em as constants. 166.Pp 167.Fn OBJ_nid2obj , 168.Fn OBJ_nid2ln , 169and 170.Fn OBJ_nid2sn 171convert the NID 172.Fa n 173to an 174.Vt ASN1_OBJECT 175structure, its long name, and its short name, respectively, or return 176.Dv NULL 177if an error occurred. 178.Pp 179.Fn OBJ_obj2nid , 180.Fn OBJ_ln2nid , 181and 182.Fn OBJ_sn2nid 183return the corresponding NID for the object 184.Fa o , 185the long name 186.Fa ln , 187or the short name 188.Fa sn , 189respectively, or 190.Dv NID_undef 191if an error occurred. 192.Pp 193.Fn OBJ_txt2nid 194returns the NID corresponding to text string 195.Fa s . 196.Fa s 197can be a long name, a short name, or the numerical representation 198of an object. 199.Pp 200.Fn OBJ_txt2obj 201converts the text string 202.Fa s 203into an 204.Vt ASN1_OBJECT 205structure. 206If 207.Fa no_name 208is 0 then long names and short names will be interpreted as well as 209numerical forms. 210If 211.Fa no_name 212is 1 only the numerical form is acceptable. 213.Pp 214.Fn OBJ_obj2txt 215converts the 216.Vt ASN1_OBJECT 217.Fa a 218into a textual representation. 219The representation is written as a NUL terminated string to 220.Fa buf . 221At most 222.Fa buf_len 223bytes are written, truncating the result if necessary. 224The total amount of space required is returned. 225If 226.Fa no_name 227is 0 and the object has a long or short name, then that will be used, 228otherwise the numerical form will be used. 229.Pp 230.Fn i2t_ASN1_OBJECT 231is the same as 232.Fn OBJ_obj2txt 233with 234.Fa no_name 235set to 0. 236.Pp 237.Fn OBJ_cmp 238compares 239.Fa a 240to 241.Fa b . 242If the two are identical, 0 is returned. 243.Pp 244.Fn OBJ_dup 245returns a deep copy of 246.Fa o 247if 248.Fa o 249is marked as dynamically allocated. 250The new object and all data contained in it is marked as dynamically 251allocated. 252If 253.Fa o 254is not marked as dynamically allocated, 255.Fn OBJ_dup 256just returns 257.Fa o 258itself. 259.Pp 260.Fn OBJ_create 261adds a new object to the internal table. 262.Fa oid 263is the numerical form of the object, 264.Fa sn 265the short name and 266.Fa ln 267the long name. 268A new NID is returned for the created object. 269.Pp 270The new object added to the internal table and all the data 271contained in it is marked as not dynamically allocated. 272Consequently, retrieving it with 273.Fn OBJ_nid2obj 274or a similar function and then calling 275.Xr ASN1_OBJECT_free 3 276on the returned pointer will have no effect. 277.Pp 278.Fn OBJ_cleanup 279cleans up the internal object table: this should be called before 280an application exits if any new objects were added using 281.Fn OBJ_create . 282.Pp 283Objects can have a short name, a long name, and a numerical 284identifier (NID) associated with them. 285A standard set of objects is represented in an internal table. 286The appropriate values are defined in the header file 287.In openssl/objects.h . 288.Pp 289For example, the OID for commonName has the following definitions: 290.Bd -literal 291#define SN_commonName "CN" 292#define LN_commonName "commonName" 293#define NID_commonName 13 294.Ed 295.Pp 296New objects can be added by calling 297.Fn OBJ_create . 298.Pp 299Table objects have certain advantages over other objects: for example 300their NIDs can be used in a C language switch statement. 301They are also static constant structures which are shared: that is there 302is only a single constant structure for each table object. 303.Pp 304Objects which are not in the table have the NID value 305.Dv NID_undef . 306.Pp 307Objects do not need to be in the internal tables to be processed: 308the functions 309.Fn OBJ_txt2obj 310and 311.Fn OBJ_obj2txt 312can process the numerical form of an OID. 313.Sh RETURN VALUES 314.Fn OBJ_nid2obj 315and 316.Fn OBJ_dup 317return an 318.Vt ASN1_OBJECT 319object or 320.Dv NULL 321if an error occurs. 322.Pp 323.Fn OBJ_nid2ln 324and 325.Fn OBJ_nid2sn 326return a valid string or 327.Dv NULL 328on error. 329.Pp 330.Fn OBJ_obj2nid , 331.Fn OBJ_ln2nid , 332.Fn OBJ_sn2nid , 333and 334.Fn OBJ_txt2nid 335return a NID or 336.Dv NID_undef 337on error. 338.Pp 339.Fn OBJ_create 340returns the new NID or 341.Dv NID_undef 342if an error occurs. 343.Pp 344In some cases of failure of 345.Fn OBJ_nid2obj , 346.Fn OBJ_nid2ln , 347.Fn OBJ_nid2sn , 348.Fn OBJ_txt2nid , 349.Fn OBJ_txt2obj , 350.Fn OBJ_obj2txt , 351.Fn OBJ_dup , 352.Fn OBJ_create , 353and 354.Fn i2t_ASN1_OBJECT , 355the reason can be determined with 356.Xr ERR_get_error 3 . 357.Sh EXAMPLES 358Create an object for 359.Sy commonName : 360.Bd -literal -offset indent 361ASN1_OBJECT *o; 362o = OBJ_nid2obj(NID_commonName); 363.Ed 364.Pp 365Check if an object is 366.Sy commonName : 367.Bd -literal -offset indent 368if (OBJ_obj2nid(obj) == NID_commonName) 369 /* Do something */ 370.Ed 371.Pp 372Create a new NID and initialize an object from it: 373.Bd -literal -offset indent 374int new_nid; 375ASN1_OBJECT *obj; 376new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); 377obj = OBJ_nid2obj(new_nid); 378.Ed 379.Pp 380Create a new object directly: 381.Bd -literal -offset indent 382obj = OBJ_txt2obj("1.2.3.4", 1); 383.Ed 384.Sh SEE ALSO 385.Xr ASN1_OBJECT_new 3 , 386.Xr d2i_ASN1_OBJECT 3 387.Sh HISTORY 388.Fn OBJ_nid2obj , 389.Fn OBJ_nid2ln , 390.Fn OBJ_nid2sn , 391.Fn OBJ_obj2nid , 392.Fn OBJ_ln2nid , 393.Fn OBJ_sn2nid , 394.Fn OBJ_txt2nid , 395.Fn OBJ_cmp , 396and 397.Fn OBJ_dup 398first appeared in SSLeay 0.5.1. 399.Fn OBJ_cleanup 400first appeared in SSLeay 0.8.0. 401.Fn OBJ_create 402and 403.Fn i2t_ASN1_OBJECT 404first appeared in SSLeay 0.9.0. 405All these functions have been available since 406.Ox 2.4 . 407.Pp 408.Fn OBJ_txt2obj 409first appeared in OpenSSL 0.9.2b. 410.Fn OBJ_obj2txt 411first appeared in OpenSSL 0.9.4. 412Both functions have been available since 413.Ox 2.6 . 414.Sh BUGS 415.Fn OBJ_obj2txt 416is awkward and messy to use: it doesn't follow the convention of other 417OpenSSL functions where the buffer can be set to 418.Dv NULL 419to determine the amount of data that should be written. 420Instead 421.Fa buf 422must point to a valid buffer and 423.Fa buf_len 424should be set to a positive value. 425A buffer length of 80 should be more than enough to handle any OID 426encountered in practice. 427