1.\" $OpenBSD: ASN1_OBJECT_new.3,v 1.16 2023/09/05 15:01:39 schwarze Exp $ 2.\" full merge up to: OpenSSL 99d63d4 Mar 19 12:28:58 2016 -0400 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, 2023 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. 22.\" Copyright (c) 2002, 2006 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: September 5 2023 $ 69.Dt ASN1_OBJECT_NEW 3 70.Os 71.Sh NAME 72.Nm ASN1_OBJECT_new , 73.Nm ASN1_OBJECT_create , 74.Nm ASN1_OBJECT_free 75.Nd ASN.1 object identifiers 76.Sh SYNOPSIS 77.In openssl/asn1.h 78.Ft ASN1_OBJECT * 79.Fo ASN1_OBJECT_new 80.Fa void 81.Fc 82.Ft ASN1_OBJECT * 83.Fo ASN1_OBJECT_create 84.Fa "int nid" 85.Fa "unsigned char *content" 86.Fa "int len" 87.Fa "const char *short_name" 88.Fa "const char *long_name" 89.Fc 90.Ft void 91.Fo ASN1_OBJECT_free 92.Fa "ASN1_OBJECT *a" 93.Fc 94.Sh DESCRIPTION 95.Fn ASN1_OBJECT_new 96allocates and initializes an empty 97.Vt ASN1_OBJECT 98object, representing an ASN.1 OBJECT IDENTIFIER. 99It can hold a short name, a long name, a numeric identifier (NID), 100and a sequence of integers identifying a node in the International 101Object Identifier tree as specified in ITU-T recommendation X.660. 102The new object is marked as dynamically allocated. 103.Pp 104The ASN.1 object identifier type is also represented by the 105.Dv V_ASN1_OBJECT 106type identifier constant. 107.Pp 108.Fn ASN1_OBJECT_create 109allocates a new 110.Vt ASN1_OBJECT 111with the given 112.Fa nid , 113copies the 114.Fa len 115DER 116.Fa content 117octets, the 118.Fa short_name , 119and the 120.Fa long_name 121into it, and marks the new object and all data contained in it 122as dynamically allocated. 123.Pp 124Application programs normally use utility functions like 125.Xr OBJ_nid2obj 3 126rather than using 127.Fn ASN1_OBJECT_new 128or 129.Fn ASN1_OBJECT_create 130directly. 131.Pp 132.Fn ASN1_OBJECT_free 133has the following effects: 134.Pp 135All data contained in 136.Fa a 137that is marked as dynamically allocated is freed, 138and the respective fields of 139.Fa a 140become empty. 141Contained data not marked as dynamically allocated remains intact. 142.Pp 143If the object 144.Fa a 145itself is marked as dynamically allocated, it is freed. 146Otherwise, the pointer 147.Fa a 148remains valid. 149.Pp 150If 151.Fa a 152is a 153.Dv NULL 154pointer or if neither the object itself nor any of its content 155is marked as dynamically allocated, no action occurs. 156.Sh RETURN VALUES 157.Fn ASN1_OBJECT_new 158and 159.Fn ASN1_OBJECT_create 160return a pointer to the new object or 161.Dv NULL 162if memory allocation fails, 163.Sh ERRORS 164After failure of 165.Fn ASN1_OBJECT_new 166or 167.Fn ASN1_OBJECT_create , 168the following diagnostic can be retrieved with 169.Xr ERR_get_error 3 , 170.Xr ERR_GET_REASON 3 , 171and 172.Xr ERR_reason_error_string 3 : 173.Bl -tag -width Ds 174.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" 175Memory allocation failed. 176.El 177.Pp 178After some cases of failure of 179.Fn ASN1_OBJECT_create , 180the following diagnostic can be retrieved in addition to the above: 181.Bl -tag -width Ds 182.It Dv ERR_R_ASN1_LIB Qq "ASN1 lib" 183Memory allocation failed. 184.El 185.Sh SEE ALSO 186.Xr a2d_ASN1_OBJECT 3 , 187.Xr ASN1_TYPE_get 3 , 188.Xr d2i_ASN1_OBJECT 3 , 189.Xr OBJ_create 3 , 190.Xr OBJ_nid2obj 3 191.Sh STANDARDS 192ITU-T Recommendation X.208, also known as ISO/IEC 8824-1: 193Specification of Abstract Syntax Notation One (ASN.1), 194section 28: Notation for the object identifier type 195.Pp 196ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: 197Information technology - ASN.1 encoding rules: 198Specification of Basic Encoding Rules (BER), Canonical Encoding 199Rules (CER) and Distinguished Encoding Rules (DER), 200section 8.19: Encoding of an object identifier value 201.Sh HISTORY 202.Fn ASN1_OBJECT_new 203and 204.Fn ASN1_OBJECT_free 205first appeared in SSLeay 0.5.1 and 206.Fn ASN1_OBJECT_create 207in SSLeay 0.8.0. 208These functions have been available since 209.Ox 2.4 . 210.Sh BUGS 211The function 212.Fn ASN1_OBJECT_new 213is not useful for any practical purpose because the library does not 214provide any function capable of adding data to an existing object. 215Consequently, if the application program creates an object with 216.Fn ASN1_OBJECT_new , 217that object will always remain empty. 218.Pp 219Similarly, if an 220.Fa nid 221of 222.Dv NID_undef 223is passed to 224.Fn ASN1_OBJECT_create , 225or if 226.Dv NULL 227is passed for any of its pointer arguments, the returned object 228will permanently remain incomplete. 229