1.\"     $OpenBSD: ASN1_item_new.3,v 1.5 2019/06/14 13:59:32 schwarze 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: June 14 2019 $
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 ASN1_BOOLEAN_it
91or
92.Dv LONG_it ,
93.Fn ASN1_item_new
94does not return a pointer at all, but a
95.Vt long
96value cast to
97.Vt ASN1_VALUE * .
98.Sh RETURN VALUES
99The
100.Fn ASN1_item_new
101function returns the new
102.Vt ASN1_VALUE
103object if successful; otherwise
104.Dv NULL
105is returned and an error code can be retrieved with
106.Xr ERR_get_error 3 .
107.Sh SEE ALSO
108.Xr ASN1_item_d2i 3 ,
109.Xr ASN1_TYPE_new 3 ,
110.Xr d2i_ASN1_NULL 3 ,
111.Xr OBJ_nid2obj 3
112.Sh HISTORY
113.Fn ASN1_item_new
114and
115.Fn ASN1_item_free
116first appeared in OpenSSL 0.9.7 and have been available since
117.Ox 3.2 .
118.Sh BUGS
119The
120.Vt ASN1_VALUE
121type compromises type safety and invites programming mistakes that
122will typically have severe consequences.
123