1.\" $OpenBSD: OBJ_create.3,v 1.8 2023/09/06 12:26:59 schwarze Exp $ 2.\" full merge up to: 3.\" OpenSSL OBJ_nid2obj.pod 9b86974e Aug 17 15:21:33 2015 -0400 4.\" selective merge up to: 5.\" OpenSSL OBJ_nid2obj.pod 0c5bc96f Mar 15 13:57:22 2022 +0000 6.\" 7.\" This file is a derived work. 8.\" The changes are covered by the following Copyright and license: 9.\" 10.\" Copyright (c) 2017, 2021, 2023 Ingo Schwarze <schwarze@openbsd.org> 11.\" 12.\" Permission to use, copy, modify, and distribute this software for any 13.\" purpose with or without fee is hereby granted, provided that the above 14.\" copyright notice and this permission notice appear in all copies. 15.\" 16.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 17.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 18.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 19.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 20.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 21.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 22.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 23.\" 24.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 25.\" Copyright (c) 2002, 2006 The OpenSSL Project. 26.\" All rights reserved. 27.\" 28.\" Redistribution and use in source and binary forms, with or without 29.\" modification, are permitted provided that the following conditions 30.\" are met: 31.\" 32.\" 1. Redistributions of source code must retain the above copyright 33.\" notice, this list of conditions and the following disclaimer. 34.\" 35.\" 2. Redistributions in binary form must reproduce the above copyright 36.\" notice, this list of conditions and the following disclaimer in 37.\" the documentation and/or other materials provided with the 38.\" distribution. 39.\" 40.\" 3. All advertising materials mentioning features or use of this 41.\" software must display the following acknowledgment: 42.\" "This product includes software developed by the OpenSSL Project 43.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 44.\" 45.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 46.\" endorse or promote products derived from this software without 47.\" prior written permission. For written permission, please contact 48.\" openssl-core@openssl.org. 49.\" 50.\" 5. Products derived from this software may not be called "OpenSSL" 51.\" nor may "OpenSSL" appear in their names without prior written 52.\" permission of the OpenSSL Project. 53.\" 54.\" 6. Redistributions of any form whatsoever must retain the following 55.\" acknowledgment: 56.\" "This product includes software developed by the OpenSSL Project 57.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 58.\" 59.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 60.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 61.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 62.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 63.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 64.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 65.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 66.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 67.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 68.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 69.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 70.\" OF THE POSSIBILITY OF SUCH DAMAGE. 71.\" 72.Dd $Mdocdate: September 6 2023 $ 73.Dt OBJ_CREATE 3 74.Os 75.Sh NAME 76.Nm OBJ_new_nid , 77.Nm OBJ_add_object , 78.Nm OBJ_create , 79.\" OBJ_create_and_add_object is a deprecated, unused alias for OBJ_create(3). 80.Nm OBJ_create_objects , 81.Nm obj_cleanup_defer , 82.Nm OBJ_cleanup , 83.Nm check_defer 84.Nd modify the table of ASN.1 object identifiers 85.Sh SYNOPSIS 86.In openssl/objects.h 87.Ft int 88.Fn OBJ_new_nid "int increment" 89.Ft int 90.Fn OBJ_add_object "const ASN1_OBJECT *object" 91.Ft int 92.Fo OBJ_create 93.Fa "const char *oid" 94.Fa "const char *sn" 95.Fa "const char *ln" 96.Fc 97.Ft int 98.Fn OBJ_create_objects "BIO *in_bio" 99.Vt extern int obj_cleanup_defer ; 100.Ft void 101.Fn OBJ_cleanup void 102.Ft void 103.Fn check_defer "int nid" 104.Sh DESCRIPTION 105.Fn OBJ_new_nid 106returns the smallest currently unassigned ASN.1 numeric 107object identifier (NID) and reserves 108.Fa increment 109consecutive NIDs starting with it. 110Passing an argument of 1 is usually recommended. 111The return value can be assigned to a new object by passing it as the 112.Fa nid 113argument to 114.Xr ASN1_OBJECT_create 3 115and by passing the resulting object to 116.Fn OBJ_add_object . 117.Pp 118.Fn OBJ_add_object 119adds a copy of the 120.Fa object 121to the internal table of ASN.1 object identifiers for use by 122.Xr OBJ_nid2obj 3 123and related functions. 124.Pp 125.Fn OBJ_create 126provides a simpler way to add a new object to the internal table. 127.Fa oid 128is the numerical form of the object, 129.Fa sn 130the short name and 131.Fa ln 132the long name. 133A new NID is automatically assigned using 134.Fn OBJ_new_nid . 135.Pp 136.Fn OBJ_create_objects 137reads text lines of the form 138.Pp 139.D1 Fa oid sn ln 140.Pp 141from 142.Fa in_bio 143and calls 144.Fn OBJ_create oid sn ln 145for every line read. 146The three fields of the input lines 147are separated by one or more whitespace characters. 148.Pp 149For all three functions, the objects added to the internal table and 150all the data contained in them is marked as not dynamically allocated. 151Consequently, retrieving them with 152.Xr OBJ_nid2obj 3 153or a similar function and then calling 154.Xr ASN1_OBJECT_free 3 155on the returned pointer will have no effect. 156.Pp 157The global variable 158.Va obj_cleanup_defer 159controls the behaviour of 160.Fn OBJ_cleanup 161and 162.Xr EVP_cleanup 3 . 163.Pp 164If 165.Va obj_cleanup_defer 166has the default value of 0, 167.Fn OBJ_cleanup 168resets the internal object table to its default state, 169removing and freeing all objects that were added with 170.Fn OBJ_add_object , 171.Fn OBJ_create , 172or 173.Fn OBJ_create_objects . 174Otherwise, 175.Fn OBJ_cleanup 176only sets 177.Va obj_cleanup_defer 178to 2, which defers the cleanup of the internal object table 179to the next call of 180.Xr EVP_cleanup 3 . 181.Pp 182By default, 183.Xr EVP_cleanup 3 184has no effect on the internal object table. 185Only if 186.Va obj_cleanup_defer 187is 2, it resets 188.Va obj_cleanup_defer 189to 0 and calls 190.Fn OBJ_cleanup , 191which then resets the table to its default state. 192.Pp 193The function 194.Fn check_defer 195sets 196.Va obj_cleanup_defer 197to 1 unless 198.Fa nid 199is a built-in numeric identifier, but it has no effect if 200.Va obj_cleanup_defer 201already differs from 0. 202This function is called internally by various functions 203in the EVP library, in particular by subroutines of 204.Xr OpenSSL_add_all_ciphers 3 205and 206.Xr OpenSSL_add_all_digests 3 . 207.Pp 208To reliably reset the internal object table no matter what the 209current state may be, an application program needs to call both 210.Fn OBJ_cleanup 211and 212.Xr EVP_cleanup 3 , 213in this order. 214The opposite order will usually not work. 215.Sh RETURN VALUES 216.Fn OBJ_new_nid 217returns the new NID. 218.Pp 219.Fn OBJ_add_object 220returns the NID of the added 221.Fa object 222or 223.Dv NID_undef 224if no object was added because the 225.Fa object 226argument was 227.Dv NULL , 228did not contain an NID, or memory allocation failed. 229.Pp 230.Fn OBJ_create 231returns the new NID or 232.Dv NID_undef 233if 234.Fa oid 235is not a valid representation of an object identifier 236or if memory allocation fails. 237.Pp 238.Fn OBJ_create_objects 239returns the number of objects added. 240.Pp 241In some cases of failure of 242.Fn OBJ_add_object , 243.Fn OBJ_create , 244and 245.Fn OBJ_create_objects , 246the reason can be determined with 247.Xr ERR_get_error 3 . 248.Sh EXAMPLES 249Create a new NID and initialize an object from it: 250.Bd -literal -offset indent 251int new_nid; 252ASN1_OBJECT *obj; 253 254new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); 255obj = OBJ_nid2obj(new_nid); 256.Ed 257.Sh SEE ALSO 258.Xr ASN1_OBJECT_new 3 , 259.Xr EVP_cleanup 3 , 260.Xr OBJ_NAME_add 3 , 261.Xr OBJ_nid2obj 3 262.Sh HISTORY 263.Fn OBJ_new_nid , 264.Fn OBJ_add_object , 265and 266.Fn OBJ_cleanup 267first appeared in SSLeay 0.8.0 and 268.Fn OBJ_create 269in SSLeay 0.9.0. 270These functions have been available since 271.Ox 2.4 . 272.Pp 273.Va obj_cleanup_defer 274and 275.Fn check_defer 276first appeared in OpenSSL 1.0.0 and have been available since 277.Ox 4.9 . 278.Sh CAVEATS 279.Fn OBJ_add_object 280indicates success even after adding an incomplete object that was created with 281.Xr ASN1_OBJECT_create 3 282but lacks a short name, a long name, or an OID. 283.Pp 284Even 285.Fn OBJ_create 286tolerates 287.Dv NULL 288pointers being passed for the 289.Fa sn 290and/or 291.Fa ln 292arguments, in which case 293.Xr OBJ_nid2sn 3 294and 295.Xr OBJ_sn2nid 3 296or 297.Xr OBJ_nid2ln 3 298and 299.Xr OBJ_ln2nid 3 300will not work on the added object, respectively. 301.Sh BUGS 302.Fn OBJ_new_nid 303does not reserve any return value to indicate an error. 304Consequently, to avoid conflicting NID assignments and integer overflows, 305care must be taken to not pass negative, zero, or large arguments to 306.Fn OBJ_new_nid . 307.Pp 308.Fn OBJ_create_objects 309does not distinguish between end of file, I/O errors, temporary 310unavailability of data on a non-blocking BIO, invalid input syntax, 311and memory allocation failure. 312In all these cases, reading is aborted and the number of objects 313that were already added is returned. 314