1.\" $OpenBSD: OBJ_nid2obj.3,v 1.16 2021/12/15 20:07:51 schwarze Exp $ 2.\" full merge up to: OpenSSL c264592d May 14 11:28:00 2006 +0000 3.\" selective merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2017, 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, 2006, 2016 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: December 15 2021 $ 71.Dt OBJ_NID2OBJ 3 72.Os 73.Sh NAME 74.Nm OBJ_nid2obj , 75.Nm OBJ_nid2ln , 76.Nm OBJ_nid2sn , 77.Nm OBJ_obj2nid , 78.Nm OBJ_ln2nid , 79.Nm OBJ_sn2nid , 80.Nm OBJ_txt2nid , 81.Nm OBJ_txt2obj , 82.Nm OBJ_obj2txt , 83.Nm OBJ_cmp , 84.Nm OBJ_dup , 85.Nm i2t_ASN1_OBJECT , 86.Nm i2a_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.In openssl/asn1.h 140.Ft int 141.Fo i2t_ASN1_OBJECT 142.Fa "char *buf" 143.Fa "int buf_len" 144.Fa "const ASN1_OBJECT *a" 145.Fc 146.Ft int 147.Fo i2a_ASN1_OBJECT 148.Fa "BIO *out_bio" 149.Fa "const ASN1_OBJECT *a" 150.Fc 151.Sh DESCRIPTION 152The ASN.1 object utility functions process 153.Vt ASN1_OBJECT 154structures which are a representation of the ASN.1 OBJECT IDENTIFIER 155(OID) type. 156For convenience, OIDs are usually represented in source code as 157numeric identifiers, or NIDs. 158OpenSSL has an internal table of OIDs that are generated when the 159library is built, and their corresponding NIDs are available as 160defined constants. 161For the functions below, application code should treat all returned 162values \(em OIDs, NIDs, or names \(em as constants. 163.Pp 164.Fn OBJ_nid2obj , 165.Fn OBJ_nid2ln , 166and 167.Fn OBJ_nid2sn 168convert the NID 169.Fa n 170to an 171.Vt ASN1_OBJECT 172structure, its long name, and its short name, respectively, or return 173.Dv NULL 174if an error occurred. 175.Pp 176.Fn OBJ_obj2nid , 177.Fn OBJ_ln2nid , 178and 179.Fn OBJ_sn2nid 180return the corresponding NID for the object 181.Fa o , 182the long name 183.Fa ln , 184or the short name 185.Fa sn , 186respectively, or 187.Dv NID_undef 188if an error occurred. 189.Pp 190.Fn OBJ_txt2nid 191returns the NID corresponding to text string 192.Fa s . 193.Fa s 194can be a long name, a short name, or the numerical representation 195of an object. 196.Pp 197.Fn OBJ_txt2obj 198converts the text string 199.Fa s 200into an 201.Vt ASN1_OBJECT 202structure. 203If 204.Fa no_name 205is 0 then long names and short names will be interpreted as well as 206numerical forms. 207If 208.Fa no_name 209is 1 only the numerical form is acceptable. 210.Pp 211.Fn OBJ_obj2txt 212converts the 213.Vt ASN1_OBJECT 214.Fa a 215into a textual representation. 216The representation is written as a NUL terminated string to 217.Fa buf . 218At most 219.Fa buf_len 220bytes are written, truncating the result if necessary. 221The total amount of space required is returned. 222If 223.Fa no_name 224is 0 and the object has a long or short name, then that will be used, 225otherwise the numerical form will be used. 226.Pp 227.Fn i2t_ASN1_OBJECT 228is the same as 229.Fn OBJ_obj2txt 230with 231.Fa no_name 232set to 0. 233.Pp 234.Fn i2a_ASN1_OBJECT 235writes a textual representation of 236.Fa a 237to 238.Fa out_bio 239using 240.Xr BIO_write 3 . 241It does not write a terminating NUL byte. 242If 243.Fa a 244is 245.Dv NULL 246or contains no data, it writes the 4-byte string 247.Qq NULL . 248If 249.Fn i2t_ASN1_OBJECT 250fails, 251.Fn i2a_ASN1_OBJECT 252writes the 9-byte string 253.Qq <INVALID> . 254Otherwise, it writes the string constructed with 255.Fn i2t_ASN1_OBJECT . 256.Pp 257.Fn OBJ_cmp 258compares 259.Fa a 260to 261.Fa b . 262If the two are identical, 0 is returned. 263.Pp 264.Fn OBJ_dup 265returns a deep copy of 266.Fa o 267if 268.Fa o 269is marked as dynamically allocated. 270The new object and all data contained in it is marked as dynamically 271allocated. 272If 273.Fa o 274is not marked as dynamically allocated, 275.Fn OBJ_dup 276just returns 277.Fa o 278itself. 279.Pp 280Objects can have a short name, a long name, and a numerical 281identifier (NID) associated with them. 282A standard set of objects is represented in an internal table. 283The appropriate values are defined in the header file 284.In openssl/objects.h . 285.Pp 286For example, the OID for commonName has the following definitions: 287.Bd -literal 288#define SN_commonName "CN" 289#define LN_commonName "commonName" 290#define NID_commonName 13 291.Ed 292.Pp 293New objects can be added by calling 294.Xr OBJ_create 3 . 295.Pp 296Table objects have certain advantages over other objects: for example 297their NIDs can be used in a C language switch statement. 298They are also static constant structures which are shared: that is there 299is only a single constant structure for each table object. 300.Pp 301Objects which are not in the table have the NID value 302.Dv NID_undef . 303.Pp 304Objects do not need to be in the internal tables to be processed: 305the functions 306.Fn OBJ_txt2obj 307and 308.Fn OBJ_obj2txt 309can process the numerical form of an OID. 310.Sh RETURN VALUES 311.Fn OBJ_nid2obj , 312.Fn OBJ_txt2obj , 313and 314.Fn OBJ_dup 315return an 316.Vt ASN1_OBJECT 317object or 318.Dv NULL 319if an error occurs. 320.Pp 321.Fn OBJ_nid2ln 322and 323.Fn OBJ_nid2sn 324return a valid string or 325.Dv NULL 326on error. 327.Pp 328.Fn OBJ_obj2nid , 329.Fn OBJ_ln2nid , 330.Fn OBJ_sn2nid , 331and 332.Fn OBJ_txt2nid 333return a NID or 334.Dv NID_undef 335on error. 336.Pp 337.Fn OBJ_obj2txt 338and 339.Fn i2t_ASN1_OBJECT 340return the amount of space required in bytes, 341including the terminating NUL byte. 342.Pp 343.Fn i2a_ASN1_OBJECT 344returns the number of bytes written, even if 345.Fa a 346is invalid or contains invalid data, 347but a negative value if memory allocation or a write operation fails. 348.Pp 349.Fn OBJ_cmp 350returns 0 if the contents of 351.Fa a 352and 353.Fa b 354are identical, or non-zero otherwise. 355.Pp 356In some cases of failure of 357.Fn OBJ_nid2obj , 358.Fn OBJ_nid2ln , 359.Fn OBJ_nid2sn , 360.Fn OBJ_txt2nid , 361.Fn OBJ_txt2obj , 362.Fn OBJ_obj2txt , 363.Fn OBJ_dup , 364.Fn i2t_ASN1_OBJECT , 365and 366.Fn i2a_ASN1_OBJECT , 367the reason can be determined with 368.Xr ERR_get_error 3 . 369.Sh EXAMPLES 370Create an object for 371.Sy commonName : 372.Bd -literal -offset indent 373ASN1_OBJECT *o; 374o = OBJ_nid2obj(NID_commonName); 375.Ed 376.Pp 377Check if an object is 378.Sy commonName : 379.Bd -literal -offset indent 380if (OBJ_obj2nid(obj) == NID_commonName) 381 /* Do something */ 382.Ed 383.Pp 384Create a new object directly: 385.Bd -literal -offset indent 386obj = OBJ_txt2obj("1.2.3.4", 1); 387.Ed 388.Sh SEE ALSO 389.Xr ASN1_OBJECT_new 3 , 390.Xr BIO_new 3 , 391.Xr d2i_ASN1_OBJECT 3 , 392.Xr OBJ_create 3 393.Sh HISTORY 394.Fn OBJ_nid2obj , 395.Fn OBJ_nid2ln , 396.Fn OBJ_nid2sn , 397.Fn OBJ_obj2nid , 398.Fn OBJ_ln2nid , 399.Fn OBJ_sn2nid , 400.Fn OBJ_txt2nid , 401.Fn OBJ_cmp , 402and 403.Fn OBJ_dup 404first appeared in SSLeay 0.5.1. 405.Fn i2a_ASN1_OBJECT 406first appeared in SSLeay 0.6.0, and 407.Fn i2t_ASN1_OBJECT 408in SSLeay 0.9.0. 409All these functions have been available since 410.Ox 2.4 . 411.Pp 412.Fn OBJ_txt2obj 413first appeared in OpenSSL 0.9.2b. 414.Fn OBJ_obj2txt 415first appeared in OpenSSL 0.9.4. 416Both functions have been available since 417.Ox 2.6 . 418.Sh BUGS 419.Fn OBJ_obj2txt 420is awkward and messy to use: it doesn't follow the convention of other 421OpenSSL functions where the buffer can be set to 422.Dv NULL 423to determine the amount of data that should be written. 424Instead 425.Fa buf 426must point to a valid buffer and 427.Fa buf_len 428should be set to a positive value. 429A buffer length of 80 should be more than enough to handle any OID 430encountered in practice. 431