1.\" $OpenBSD: OBJ_create.3,v 1.6 2022/01/01 02:06:07 jsg 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 35fd9953 May 28 14:49:38 2019 +0200 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 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: January 1 2022 $ 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 associated with the 221.Fa object 222or 223.Dv NID_undef 224if memory allocation fails. 225.Pp 226.Fn OBJ_create 227returns the new NID or 228.Dv NID_undef 229if 230.Fa oid 231is not a valid representation of an object identifier 232or if memory allocation fails. 233.Pp 234.Fn OBJ_create_objects 235returns the number of objects added. 236.Pp 237In some cases of failure of 238.Fn OBJ_add_object , 239.Fn OBJ_create , 240and 241.Fn OBJ_create_objects , 242the reason can be determined with 243.Xr ERR_get_error 3 . 244.Sh EXAMPLES 245Create a new NID and initialize an object from it: 246.Bd -literal -offset indent 247int new_nid; 248ASN1_OBJECT *obj; 249 250new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); 251obj = OBJ_nid2obj(new_nid); 252.Ed 253.Sh SEE ALSO 254.Xr ASN1_OBJECT_new 3 , 255.Xr EVP_cleanup 3 , 256.Xr OBJ_add_sigid 3 , 257.Xr OBJ_NAME_add 3 , 258.Xr OBJ_nid2obj 3 259.Sh HISTORY 260.Fn OBJ_new_nid , 261.Fn OBJ_add_object , 262and 263.Fn OBJ_cleanup 264first appeared in SSLeay 0.8.0 and 265.Fn OBJ_create 266in SSLeay 0.9.0. 267These functions have been available since 268.Ox 2.4 . 269.Pp 270.Va obj_cleanup_defer 271and 272.Fn check_defer 273first appeared in OpenSSL 1.0.0 and have been available since 274.Ox 4.9 . 275.Sh BUGS 276.Fn OBJ_new_nid 277does not reserve any return value to indicate an error. 278Consequently, to avoid conflicting NID assignments and integer overflows, 279care must be taken to not pass negative, zero, or large arguments to 280.Fn OBJ_new_nid . 281.Pp 282.Fn OBJ_create_objects 283does not distinguish between end of file, I/O errors, temporary 284unavailability of data on a non-blocking BIO, invalid input syntax, 285and memory allocation failure. 286In all these cases, reading is aborted and the number of objects 287that were already added is returned. 288