1.\" $OpenBSD: ASN1_item_new.3,v 1.11 2022/01/12 17:54:51 tb Exp $ 2.\" 3.\" Copyright (c) 2016, 2018 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: January 12 2022 $ 18.Dt ASN1_ITEM_NEW 3 19.Os 20.Sh NAME 21.Nm ASN1_item_new , 22.Nm ASN1_item_free 23.Nd generic ASN.1 value constructor and destructor 24.Sh SYNOPSIS 25.In openssl/asn1.h 26.Ft ASN1_VALUE * 27.Fo ASN1_item_new 28.Fa "const ASN1_ITEM *it" 29.Fc 30.Ft void 31.Fo ASN1_item_free 32.Fa "ASN1_VALUE *val_in" 33.Fa "const ASN1_ITEM *it" 34.Fc 35.Sh DESCRIPTION 36.Fn ASN1_item_new 37allocates and initializes an empty ASN.1 value 38of the type described by the global static object 39.Fa it . 40.Pp 41If the item type described by 42.Fa it 43is reference counted, 44.Fn ASN1_item_free 45decrements the reference count of 46.Fa val_in . 47Otherwise, or if the reference count reaches 0, 48.Fn ASN1_item_free 49frees 50.Fa val_in , 51assuming that it is of the type described by 52.Fa it . 53If the true type of 54.Fa val_in 55fails to match the specified 56.Fa it , 57buffer overflows and segmentation faults are likely to occur. 58It is not possible to recover the type of an 59.Vt ASN1_VALUE 60object by inspecting it; the type always needs to be remembered 61separately. 62.Pp 63.Vt ASN1_VALUE 64is an incomplete type, and pointers to it always require casting 65to the correct complete type before they can be dereferenced. 66For all practical purposes, a pointer to 67.Vt ASN1_VALUE 68is equivalent to a 69.Vt void 70pointer. 71.Pp 72Depending on 73.Fa it , 74there are more than 150 different types that 75.Fn ASN1_item_new 76may return. 77Most of them are pointers to structures or pointers to arrays of 78structures, but there are a few exceptions, for example: 79If 80.Fa it 81is 82.Dv ASN1_NULL_it , 83.Fn ASN1_item_new 84returns a specific invalid pointer representing the unique 85.Vt ASN1_NULL 86object. 87If 88.Fa it 89is 90.Dv LONG_it , 91.Fn ASN1_item_new 92does not return a pointer at all, but a 93.Vt long 94value cast to 95.Vt ASN1_VALUE * . 96.Sh RETURN VALUES 97The 98.Fn ASN1_item_new 99function returns the new 100.Vt ASN1_VALUE 101object if successful; otherwise 102.Dv NULL 103is returned and an error code can be retrieved with 104.Xr ERR_get_error 3 . 105.Sh SEE ALSO 106.Xr ASN1_get_object 3 , 107.Xr ASN1_item_d2i 3 , 108.Xr ASN1_item_digest 3 , 109.Xr ASN1_item_pack 3 , 110.Xr ASN1_item_sign 3 , 111.Xr ASN1_item_verify 3 , 112.Xr ASN1_NULL_new 3 , 113.Xr ASN1_TYPE_new 3 , 114.Xr d2i_ASN1_NULL 3 , 115.Xr OBJ_nid2obj 3 116.Sh HISTORY 117.Fn ASN1_item_new 118and 119.Fn ASN1_item_free 120first appeared in OpenSSL 0.9.7 and have been available since 121.Ox 3.2 . 122.Sh BUGS 123The 124.Vt ASN1_VALUE 125type compromises type safety and invites programming mistakes that 126will typically have severe consequences. 127