1.\" $OpenBSD: ASN1_STRING_new.3,v 1.18 2021/10/20 13:14:00 schwarze Exp $ 2.\" OpenSSL 99d63d46 Tue Mar 24 07:52:24 2015 -0400 3.\" 4.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: October 20 2021 $ 19.Dt ASN1_STRING_NEW 3 20.Os 21.Sh NAME 22.Nm ASN1_STRING_new , 23.Nm ASN1_STRING_type_new , 24.Nm ASN1_STRING_free , 25.Nm ASN1_OCTET_STRING_new , 26.Nm ASN1_OCTET_STRING_free , 27.Nm ASN1_BIT_STRING_new , 28.Nm ASN1_BIT_STRING_free , 29.Nm ASN1_INTEGER_new , 30.Nm ASN1_INTEGER_free , 31.Nm ASN1_ENUMERATED_new , 32.Nm ASN1_ENUMERATED_free , 33.Nm ASN1_UTF8STRING_new , 34.Nm ASN1_UTF8STRING_free , 35.Nm ASN1_IA5STRING_new , 36.Nm ASN1_IA5STRING_free , 37.Nm ASN1_UNIVERSALSTRING_new , 38.Nm ASN1_UNIVERSALSTRING_free , 39.Nm ASN1_BMPSTRING_new , 40.Nm ASN1_BMPSTRING_free , 41.Nm ASN1_GENERALSTRING_new , 42.Nm ASN1_GENERALSTRING_free , 43.Nm ASN1_T61STRING_new , 44.Nm ASN1_T61STRING_free , 45.Nm ASN1_VISIBLESTRING_new , 46.Nm ASN1_VISIBLESTRING_free , 47.Nm ASN1_PRINTABLESTRING_new , 48.Nm ASN1_PRINTABLESTRING_free , 49.Nm ASN1_PRINTABLE_new , 50.Nm ASN1_PRINTABLE_free , 51.Nm DIRECTORYSTRING_new , 52.Nm DIRECTORYSTRING_free , 53.Nm DISPLAYTEXT_new , 54.Nm DISPLAYTEXT_free , 55.Nm ASN1_GENERALIZEDTIME_new , 56.Nm ASN1_GENERALIZEDTIME_free , 57.Nm ASN1_UTCTIME_new , 58.Nm ASN1_UTCTIME_free , 59.Nm ASN1_TIME_new , 60.Nm ASN1_TIME_free 61.Nd allocate and free ASN1_STRING objects 62.Sh SYNOPSIS 63.In openssl/asn1.h 64.Ft ASN1_STRING * 65.Fn ASN1_STRING_new void 66.Ft ASN1_STRING * 67.Fn ASN1_STRING_type_new "int type" 68.Ft void 69.Fn ASN1_STRING_free "ASN1_STRING *a" 70.Ft ASN1_OCTET_STRING * 71.Fn ASN1_OCTET_STRING_new void 72.Ft void 73.Fn ASN1_OCTET_STRING_free "ASN1_OCTET_STRING *a" 74.Ft ASN1_BIT_STRING * 75.Fn ASN1_BIT_STRING_new void 76.Ft void 77.Fn ASN1_BIT_STRING_free "ASN1_BIT_STRING *a" 78.Ft ASN1_INTEGER * 79.Fn ASN1_INTEGER_new void 80.Ft void 81.Fn ASN1_INTEGER_free "ASN1_INTEGER *a" 82.Ft ASN1_ENUMERATED * 83.Fn ASN1_ENUMERATED_new void 84.Ft void 85.Fn ASN1_ENUMERATED_free "ASN1_ENUMERATED *a" 86.Ft ASN1_UTF8STRING * 87.Fn ASN1_UTF8STRING_new void 88.Ft void 89.Fn ASN1_UTF8STRING_free "ASN1_UTF8STRING *a" 90.Ft ASN1_IA5STRING * 91.Fn ASN1_IA5STRING_new void 92.Ft void 93.Fn ASN1_IA5STRING_free "ASN1_IA5STRING *a" 94.Ft ASN1_UNIVERSALSTRING * 95.Fn ASN1_UNIVERSALSTRING_new void 96.Ft void 97.Fn ASN1_UNIVERSALSTRING_free "ASN1_UNIVERSALSTRING *a" 98.Ft ASN1_BMPSTRING * 99.Fn ASN1_BMPSTRING_new void 100.Ft void 101.Fn ASN1_BMPSTRING_free "ASN1_BMPSTRING *a" 102.Ft ASN1_GENERALSTRING * 103.Fn ASN1_GENERALSTRING_new void 104.Ft void 105.Fn ASN1_GENERALSTRING_free "ASN1_GENERALSTRING *a" 106.Ft ASN1_T61STRING * 107.Fn ASN1_T61STRING_new void 108.Ft void 109.Fn ASN1_T61STRING_free "ASN1_T61STRING *a" 110.Ft ASN1_VISIBLESTRING * 111.Fn ASN1_VISIBLESTRING_new void 112.Ft void 113.Fn ASN1_VISIBLESTRING_free "ASN1_VISIBLESTRING *a" 114.Ft ASN1_PRINTABLESTRING * 115.Fn ASN1_PRINTABLESTRING_new void 116.Ft void 117.Fn ASN1_PRINTABLESTRING_free "ASN1_PRINTABLESTRING *a" 118.Ft ASN1_STRING * 119.Fn ASN1_PRINTABLE_new void 120.Ft void 121.Fn ASN1_PRINTABLE_free "ASN1_STRING *a" 122.Ft ASN1_STRING * 123.Fn DIRECTORYSTRING_new void 124.Ft void 125.Fn DIRECTORYSTRING_free "ASN1_STRING *a" 126.Ft ASN1_STRING * 127.Fn DISPLAYTEXT_new void 128.Ft void 129.Fn DISPLAYTEXT_free "ASN1_STRING *a" 130.Ft ASN1_GENERALIZEDTIME * 131.Fn ASN1_GENERALIZEDTIME_new void 132.Ft void 133.Fn ASN1_GENERALIZEDTIME_free "ASN1_GENERALIZEDTIME *a" 134.Ft ASN1_UTCTIME * 135.Fn ASN1_UTCTIME_new void 136.Ft void 137.Fn ASN1_UTCTIME_free "ASN1_UTCTIME *a" 138.Ft ASN1_TIME * 139.Fn ASN1_TIME_new void 140.Ft void 141.Fn ASN1_TIME_free "ASN1_TIME *a" 142.Sh DESCRIPTION 143The 144.Vt ASN1_STRING 145object can represent a variety of ASN.1 built-in types. 146It can store a type and a value. 147.Pp 148All the 149.Fn *_new 150functions 151allocate and initialize an empty 152.Vt ASN1_STRING 153object. 154The following table shows the type assigned to the new object, 155and which ASN.1 type it represents. 156.Bl -column "ASN1_GENERALIZEDTIME_new()" "V_ASN1_GENERALIZEDTIME" 157.It Em constructor function Ta Em OpenSSL type Ta Em ASN.1 type 158.It Ta 159.It Fn ASN1_STRING_new Ta Dv V_ASN1_OCTET_STRING 160.It Fn ASN1_STRING_type_new Ta Fa type No argument 161.It Ta 162.It Fn ASN1_OCTET_STRING_new Ta Dv V_ASN1_OCTET_STRING Ta OCTET STRING 163.It Fn ASN1_BIT_STRING_new Ta Dv V_ASN1_BIT_STRING Ta BIT STRING 164.It Fn ASN1_INTEGER_new Ta Dv V_ASN1_INTEGER Ta INTEGER 165.It Fn ASN1_ENUMERATED_new Ta Dv V_ASN1_ENUMERATED Ta ENUMERATED 166.It Ta 167.It Fn ASN1_UTF8STRING_new Ta Dv V_ASN1_UTF8STRING Ta UTF8String 168.It Fn ASN1_IA5STRING_new Ta Dv V_ASN1_IA5STRING Ta IA5String 169.It Ta 170.It Fn ASN1_UNIVERSALSTRING_new Ta Dv V_ASN1_UNIVERSALSTRING Ta UniversalString 171.It Fn ASN1_BMPSTRING_new Ta Dv V_ASN1_BMPSTRING Ta BMPString 172.It Fn ASN1_GENERALSTRING_new Ta Dv V_ASN1_GENERALSTRING Ta GeneralString 173.It Fn ASN1_T61STRING_new Ta Dv V_ASN1_T61STRING Ta T61String 174.It Fn ASN1_VISIBLESTRING_new Ta Dv V_ASN1_VISIBLESTRING Ta VisibleString 175.It Fn ASN1_PRINTABLESTRING_new Ta Dv V_ASN1_PRINTABLESTRING Ta PrintableString 176.It Ta 177.It Fn ASN1_PRINTABLE_new Ta Dv V_ASN1_UNDEF 178.It Fn DIRECTORYSTRING_new Ta Dv V_ASN1_UNDEF 179.It Fn DISPLAYTEXT_new Ta Dv V_ASN1_UNDEF 180.It Ta 181.It Fn ASN1_GENERALIZEDTIME_new Ta Dv V_ASN1_GENERALIZEDTIME Ta GeneralizedTime 182.It Fn ASN1_UTCTIME_new Ta Dv V_ASN1_UTCTIME Ta UTCTime 183.It Fn ASN1_TIME_new Ta Dv V_ASN1_UNDEF Ta TIME 184.El 185.Pp 186All the 187.Fn *_free 188functions free 189.Fa a 190including any data contained in it. 191If 192.Fa a 193is a 194.Dv NULL 195pointer, no action occurs. 196.Sh RETURN VALUES 197All the 198.Fn *_new 199functions return the new 200.Vt ASN1_STRING 201object if successful; otherwise 202.Dv NULL 203is returned and an error code can be retrieved with 204.Xr ERR_get_error 3 . 205.Sh SEE ALSO 206.Xr ASN1_INTEGER_get 3 , 207.Xr ASN1_mbstring_copy 3 , 208.Xr ASN1_STRING_length 3 , 209.Xr ASN1_STRING_print_ex 3 , 210.Xr ASN1_time_parse 3 , 211.Xr ASN1_TIME_set 3 , 212.Xr ASN1_TYPE_get 3 , 213.Xr d2i_ASN1_OBJECT 3 , 214.Xr d2i_ASN1_OCTET_STRING 3 , 215.Xr X509_cmp_time 3 , 216.Xr X509_EXTENSION_get_object 3 , 217.Xr X509_get_ext_by_OBJ 3 , 218.Xr X509_NAME_ENTRY_get_object 3 219.Sh HISTORY 220.Fn ASN1_OCTET_STRING_new , 221.Fn ASN1_OCTET_STRING_free , 222.Fn ASN1_BIT_STRING_new , 223.Fn ASN1_BIT_STRING_free , 224.Fn ASN1_INTEGER_new , 225.Fn ASN1_INTEGER_free , 226.Fn ASN1_IA5STRING_new , 227.Fn ASN1_IA5STRING_free , 228.Fn ASN1_T61STRING_new , 229.Fn ASN1_T61STRING_free , 230.Fn ASN1_PRINTABLESTRING_new , 231.Fn ASN1_PRINTABLESTRING_free , 232.Fn ASN1_PRINTABLE_new , 233.Fn ASN1_PRINTABLE_free , 234.Fn ASN1_UTCTIME_new , 235and 236.Fn ASN1_UTCTIME_free 237first appeared in SSLeay 0.5.1. 238.Fn ASN1_STRING_new , 239.Fn ASN1_STRING_type_new , 240and 241.Fn ASN1_STRING_free 242first appeared in SSLeay 0.6.5. 243.Fn ASN1_UNIVERSALSTRING_new , 244.Fn ASN1_UNIVERSALSTRING_free , 245.Fn ASN1_GENERALSTRING_new , 246and 247.Fn ASN1_GENERALSTRING_free 248first appeared in SSLeay 0.8.0. 249.Fn ASN1_BMPSTRING_new , 250.Fn ASN1_BMPSTRING_free , 251.Fn ASN1_GENERALIZEDTIME_new , 252and 253.Fn ASN1_GENERALIZEDTIME_free 254first appeared in SSLeay 0.9.0. 255All these functions have been available since 256.Ox 2.4 . 257.Pp 258.Fn ASN1_ENUMERATED_new , 259.Fn ASN1_ENUMERATED_free , 260.Fn ASN1_TIME_new , 261and 262.Fn ASN1_TIME_free 263first appeared in OpenSSL 0.9.2b. 264.Fn ASN1_UTF8STRING_new , 265.Fn ASN1_UTF8STRING_free , 266.Fn ASN1_VISIBLESTRING_new , 267.Fn ASN1_VISIBLESTRING_free , 268.Fn DIRECTORYSTRING_new , 269.Fn DIRECTORYSTRING_free , 270.Fn DISPLAYTEXT_new , 271and 272.Fn DISPLAYTEXT_free 273first appeared in OpenSSL 0.9.3. 274These functions have been available since 275.Ox 2.6 . 276.Sh BUGS 277.Vt ASN1_OCTET_STRING , 278.Vt ASN1_BIT_STRING , 279.Vt ASN1_INTEGER , 280.Vt ASN1_ENUMERATED , 281.Vt ASN1_UTF8STRING , 282.Vt ASN1_IA5STRING , 283.Vt ASN1_UNIVERSALSTRING , 284.Vt ASN1_BMPSTRING , 285.Vt ASN1_GENERALSTRING , 286.Vt ASN1_T61STRING , 287.Vt ASN1_VISIBLESTRING , 288.Vt ASN1_PRINTABLESTRING , 289.Vt ASN1_GENERALIZEDTIME , 290.Vt ASN1_UTCTIME , 291and 292.Vt ASN1_TIME 293are merely typedef aliases of 294.Vt ASN1_STRING 295and provide no type safety whatsoever. 296