1.\" $OpenBSD: ASN1_STRING_new.3,v 1.27 2024/12/27 15:30:17 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: December 27 2024 $ 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.\" deprecated aliases, intentionally undocumented: M_ASN1_IA5STRING_new, 62.\" M_ASN1_ENUMERATED_free, M_ASN1_INTEGER_free, M_ASN1_OCTET_STRING_free 63.Nd allocate and free ASN1_STRING objects 64.Sh SYNOPSIS 65.In openssl/asn1.h 66.Ft ASN1_STRING * 67.Fn ASN1_STRING_new void 68.Ft ASN1_STRING * 69.Fn ASN1_STRING_type_new "int type" 70.Ft void 71.Fn ASN1_STRING_free "ASN1_STRING *a" 72.Ft ASN1_OCTET_STRING * 73.Fn ASN1_OCTET_STRING_new void 74.Ft void 75.Fn ASN1_OCTET_STRING_free "ASN1_OCTET_STRING *a" 76.Ft ASN1_BIT_STRING * 77.Fn ASN1_BIT_STRING_new void 78.Ft void 79.Fn ASN1_BIT_STRING_free "ASN1_BIT_STRING *a" 80.Ft ASN1_INTEGER * 81.Fn ASN1_INTEGER_new void 82.Ft void 83.Fn ASN1_INTEGER_free "ASN1_INTEGER *a" 84.Ft ASN1_ENUMERATED * 85.Fn ASN1_ENUMERATED_new void 86.Ft void 87.Fn ASN1_ENUMERATED_free "ASN1_ENUMERATED *a" 88.Ft ASN1_UTF8STRING * 89.Fn ASN1_UTF8STRING_new void 90.Ft void 91.Fn ASN1_UTF8STRING_free "ASN1_UTF8STRING *a" 92.Ft ASN1_IA5STRING * 93.Fn ASN1_IA5STRING_new void 94.Ft void 95.Fn ASN1_IA5STRING_free "ASN1_IA5STRING *a" 96.Ft ASN1_UNIVERSALSTRING * 97.Fn ASN1_UNIVERSALSTRING_new void 98.Ft void 99.Fn ASN1_UNIVERSALSTRING_free "ASN1_UNIVERSALSTRING *a" 100.Ft ASN1_BMPSTRING * 101.Fn ASN1_BMPSTRING_new void 102.Ft void 103.Fn ASN1_BMPSTRING_free "ASN1_BMPSTRING *a" 104.Ft ASN1_GENERALSTRING * 105.Fn ASN1_GENERALSTRING_new void 106.Ft void 107.Fn ASN1_GENERALSTRING_free "ASN1_GENERALSTRING *a" 108.Ft ASN1_T61STRING * 109.Fn ASN1_T61STRING_new void 110.Ft void 111.Fn ASN1_T61STRING_free "ASN1_T61STRING *a" 112.Ft ASN1_VISIBLESTRING * 113.Fn ASN1_VISIBLESTRING_new void 114.Ft void 115.Fn ASN1_VISIBLESTRING_free "ASN1_VISIBLESTRING *a" 116.Ft ASN1_PRINTABLESTRING * 117.Fn ASN1_PRINTABLESTRING_new void 118.Ft void 119.Fn ASN1_PRINTABLESTRING_free "ASN1_PRINTABLESTRING *a" 120.Ft ASN1_STRING * 121.Fn ASN1_PRINTABLE_new void 122.Ft void 123.Fn ASN1_PRINTABLE_free "ASN1_STRING *a" 124.Ft ASN1_STRING * 125.Fn DIRECTORYSTRING_new void 126.Ft void 127.Fn DIRECTORYSTRING_free "ASN1_STRING *a" 128.Ft ASN1_STRING * 129.Fn DISPLAYTEXT_new void 130.Ft void 131.Fn DISPLAYTEXT_free "ASN1_STRING *a" 132.Ft ASN1_GENERALIZEDTIME * 133.Fn ASN1_GENERALIZEDTIME_new void 134.Ft void 135.Fn ASN1_GENERALIZEDTIME_free "ASN1_GENERALIZEDTIME *a" 136.Ft ASN1_UTCTIME * 137.Fn ASN1_UTCTIME_new void 138.Ft void 139.Fn ASN1_UTCTIME_free "ASN1_UTCTIME *a" 140.Ft ASN1_TIME * 141.Fn ASN1_TIME_new void 142.Ft void 143.Fn ASN1_TIME_free "ASN1_TIME *a" 144.Sh DESCRIPTION 145The 146.Vt ASN1_STRING 147object can represent a variety of ASN.1 built-in types. 148It can store a type and a value. 149.Pp 150All the 151.Fn *_new 152functions 153allocate and initialize an empty 154.Vt ASN1_STRING 155object. 156The following table shows the type assigned to the new object, 157and which ASN.1 type it represents. 158.Bl -column "ASN1_GENERALIZEDTIME_new()" "V_ASN1_GENERALIZEDTIME" 159.It Em constructor function Ta Em OpenSSL type Ta Em ASN.1 type 160.It Ta 161.It Fn ASN1_STRING_new Ta Dv V_ASN1_OCTET_STRING 162.It Fn ASN1_STRING_type_new Ta Fa type No argument 163.It Ta 164.It Fn ASN1_OCTET_STRING_new Ta Dv V_ASN1_OCTET_STRING Ta OCTET STRING 165.It Fn ASN1_BIT_STRING_new Ta Dv V_ASN1_BIT_STRING Ta BIT STRING 166.It Fn ASN1_INTEGER_new Ta Dv V_ASN1_INTEGER Ta INTEGER 167.It Fn ASN1_ENUMERATED_new Ta Dv V_ASN1_ENUMERATED Ta ENUMERATED 168.It Ta 169.It Fn ASN1_UTF8STRING_new Ta Dv V_ASN1_UTF8STRING Ta UTF8String 170.It Fn ASN1_IA5STRING_new Ta Dv V_ASN1_IA5STRING Ta IA5String 171.It Ta 172.It Fn ASN1_UNIVERSALSTRING_new Ta Dv V_ASN1_UNIVERSALSTRING Ta UniversalString 173.It Fn ASN1_BMPSTRING_new Ta Dv V_ASN1_BMPSTRING Ta BMPString 174.It Fn ASN1_GENERALSTRING_new Ta Dv V_ASN1_GENERALSTRING Ta GeneralString 175.It Fn ASN1_T61STRING_new Ta Dv V_ASN1_T61STRING Ta T61String 176.It Fn ASN1_VISIBLESTRING_new Ta Dv V_ASN1_VISIBLESTRING Ta VisibleString 177.It Fn ASN1_PRINTABLESTRING_new Ta Dv V_ASN1_PRINTABLESTRING Ta PrintableString 178.It Ta 179.It Fn ASN1_PRINTABLE_new Ta Dv V_ASN1_UNDEF 180.It Fn DIRECTORYSTRING_new Ta Dv V_ASN1_UNDEF 181.It Fn DISPLAYTEXT_new Ta Dv V_ASN1_UNDEF 182.It Ta 183.It Fn ASN1_GENERALIZEDTIME_new Ta Dv V_ASN1_GENERALIZEDTIME Ta GeneralizedTime 184.It Fn ASN1_UTCTIME_new Ta Dv V_ASN1_UTCTIME Ta UTCTime 185.It Fn ASN1_TIME_new Ta Dv V_ASN1_UNDEF Ta TIME 186.El 187.Pp 188All the 189.Fn *_free 190functions free 191.Fa a 192including any data contained in it. 193If 194.Fa a 195is a 196.Dv NULL 197pointer, no action occurs. 198.Sh RETURN VALUES 199All the 200.Fn *_new 201functions return the new 202.Vt ASN1_STRING 203object if successful; otherwise 204.Dv NULL 205is returned and an error code can be retrieved with 206.Xr ERR_get_error 3 . 207.Sh SEE ALSO 208.Xr a2i_ipadd 3 , 209.Xr ASN1_BIT_STRING_set 3 , 210.Xr ASN1_INTEGER_get 3 , 211.Xr ASN1_item_pack 3 , 212.Xr ASN1_mbstring_copy 3 , 213.Xr ASN1_PRINTABLE_type 3 , 214.Xr ASN1_STRING_length 3 , 215.Xr ASN1_STRING_print_ex 3 , 216.Xr ASN1_TIME_set 3 , 217.Xr ASN1_TYPE_get 3 , 218.Xr ASN1_UNIVERSALSTRING_to_string 3 , 219.Xr d2i_ASN1_OBJECT 3 , 220.Xr d2i_ASN1_OCTET_STRING 3 , 221.Xr i2a_ASN1_STRING 3 , 222.Xr s2i_ASN1_INTEGER 3 , 223.Xr X509_cmp_time 3 , 224.Xr X509_EXTENSION_get_object 3 , 225.Xr X509_get_ext_by_OBJ 3 , 226.Xr X509_NAME_ENTRY_get_object 3 227.Sh HISTORY 228.Fn ASN1_OCTET_STRING_new , 229.Fn ASN1_OCTET_STRING_free , 230.Fn ASN1_BIT_STRING_new , 231.Fn ASN1_BIT_STRING_free , 232.Fn ASN1_INTEGER_new , 233.Fn ASN1_INTEGER_free , 234.Fn ASN1_IA5STRING_new , 235.Fn ASN1_IA5STRING_free , 236.Fn ASN1_T61STRING_new , 237.Fn ASN1_T61STRING_free , 238.Fn ASN1_PRINTABLESTRING_new , 239.Fn ASN1_PRINTABLESTRING_free , 240.Fn ASN1_PRINTABLE_new , 241.Fn ASN1_PRINTABLE_free , 242.Fn ASN1_UTCTIME_new , 243and 244.Fn ASN1_UTCTIME_free 245first appeared in SSLeay 0.5.1. 246.Fn ASN1_STRING_new , 247.Fn ASN1_STRING_type_new , 248and 249.Fn ASN1_STRING_free 250first appeared in SSLeay 0.6.5. 251.Fn ASN1_UNIVERSALSTRING_new , 252.Fn ASN1_UNIVERSALSTRING_free , 253.Fn ASN1_GENERALSTRING_new , 254and 255.Fn ASN1_GENERALSTRING_free 256first appeared in SSLeay 0.8.0. 257.Fn ASN1_BMPSTRING_new , 258.Fn ASN1_BMPSTRING_free , 259.Fn ASN1_GENERALIZEDTIME_new , 260and 261.Fn ASN1_GENERALIZEDTIME_free 262first appeared in SSLeay 0.9.0. 263All these functions have been available since 264.Ox 2.4 . 265.Pp 266.Fn ASN1_ENUMERATED_new , 267.Fn ASN1_ENUMERATED_free , 268.Fn ASN1_TIME_new , 269and 270.Fn ASN1_TIME_free 271first appeared in OpenSSL 0.9.2b. 272.Fn ASN1_UTF8STRING_new , 273.Fn ASN1_UTF8STRING_free , 274.Fn ASN1_VISIBLESTRING_new , 275.Fn ASN1_VISIBLESTRING_free , 276.Fn DIRECTORYSTRING_new , 277.Fn DIRECTORYSTRING_free , 278.Fn DISPLAYTEXT_new , 279and 280.Fn DISPLAYTEXT_free 281first appeared in OpenSSL 0.9.3. 282These functions have been available since 283.Ox 2.6 . 284.Sh BUGS 285.Vt ASN1_OCTET_STRING , 286.Vt ASN1_BIT_STRING , 287.Vt ASN1_INTEGER , 288.Vt ASN1_ENUMERATED , 289.Vt ASN1_UTF8STRING , 290.Vt ASN1_IA5STRING , 291.Vt ASN1_UNIVERSALSTRING , 292.Vt ASN1_BMPSTRING , 293.Vt ASN1_GENERALSTRING , 294.Vt ASN1_T61STRING , 295.Vt ASN1_VISIBLESTRING , 296.Vt ASN1_PRINTABLESTRING , 297.Vt ASN1_GENERALIZEDTIME , 298.Vt ASN1_UTCTIME , 299and 300.Vt ASN1_TIME 301are merely typedef aliases of 302.Vt ASN1_STRING 303and provide no type safety whatsoever. 304