1.\" $OpenBSD: d2i_ASN1_OCTET_STRING.3,v 1.20 2024/02/13 12:38:43 job Exp $ 2.\" 3.\" Copyright (c) 2017 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: February 13 2024 $ 18.Dt D2I_ASN1_OCTET_STRING 3 19.Os 20.Sh NAME 21.Nm d2i_ASN1_OCTET_STRING , 22.Nm i2d_ASN1_OCTET_STRING , 23.Nm d2i_ASN1_BIT_STRING , 24.Nm i2d_ASN1_BIT_STRING , 25.Nm d2i_ASN1_INTEGER , 26.Nm i2d_ASN1_INTEGER , 27.Nm d2i_ASN1_UINTEGER , 28.Nm d2i_ASN1_ENUMERATED , 29.Nm i2d_ASN1_ENUMERATED , 30.Nm d2i_ASN1_UTF8STRING , 31.Nm i2d_ASN1_UTF8STRING , 32.Nm d2i_ASN1_IA5STRING , 33.Nm i2d_ASN1_IA5STRING , 34.Nm d2i_ASN1_UNIVERSALSTRING , 35.Nm i2d_ASN1_UNIVERSALSTRING , 36.Nm d2i_ASN1_BMPSTRING , 37.Nm i2d_ASN1_BMPSTRING , 38.Nm d2i_ASN1_GENERALSTRING , 39.Nm i2d_ASN1_GENERALSTRING , 40.Nm d2i_ASN1_T61STRING , 41.Nm i2d_ASN1_T61STRING , 42.Nm d2i_ASN1_VISIBLESTRING , 43.Nm i2d_ASN1_VISIBLESTRING , 44.Nm d2i_ASN1_PRINTABLESTRING , 45.Nm i2d_ASN1_PRINTABLESTRING , 46.Nm d2i_ASN1_PRINTABLE , 47.Nm i2d_ASN1_PRINTABLE , 48.Nm d2i_DIRECTORYSTRING , 49.Nm i2d_DIRECTORYSTRING , 50.Nm d2i_DISPLAYTEXT , 51.Nm i2d_DISPLAYTEXT , 52.Nm d2i_ASN1_GENERALIZEDTIME , 53.Nm i2d_ASN1_GENERALIZEDTIME , 54.Nm d2i_ASN1_UTCTIME , 55.Nm i2d_ASN1_UTCTIME , 56.Nm d2i_ASN1_TIME , 57.Nm i2d_ASN1_TIME 58.Nd decode and encode ASN1_STRING objects 59.Sh SYNOPSIS 60.In openssl/asn1.h 61.Ft ASN1_OCTET_STRING * 62.Fo d2i_ASN1_OCTET_STRING 63.Fa "ASN1_OCTET_STRING **val_out" 64.Fa "const unsigned char **der_in" 65.Fa "long length" 66.Fc 67.Ft int 68.Fo i2d_ASN1_OCTET_STRING 69.Fa "ASN1_OCTET_STRING *val_in" 70.Fa "unsigned char **der_out" 71.Fc 72.Ft ASN1_BIT_STRING * 73.Fo d2i_ASN1_BIT_STRING 74.Fa "ASN1_BIT_STRING **val_out" 75.Fa "const unsigned char **der_in" 76.Fa "long length" 77.Fc 78.Ft int 79.Fo i2d_ASN1_BIT_STRING 80.Fa "ASN1_BIT_STRING *val_in" 81.Fa "unsigned char **der_out" 82.Fc 83.Ft ASN1_INTEGER * 84.Fo d2i_ASN1_INTEGER 85.Fa "ASN1_INTEGER **val_out" 86.Fa "const unsigned char **der_in" 87.Fa "long length" 88.Fc 89.Ft int 90.Fo i2d_ASN1_INTEGER 91.Fa "ASN1_INTEGER *val_in" 92.Fa "unsigned char **der_out" 93.Fc 94.Ft ASN1_INTEGER * 95.Fo d2i_ASN1_UINTEGER 96.Fa "ASN1_INTEGER **val_out" 97.Fa "const unsigned char **der_in" 98.Fa "long length" 99.Fc 100.Ft ASN1_ENUMERATED * 101.Fo d2i_ASN1_ENUMERATED 102.Fa "ASN1_ENUMERATED **val_out" 103.Fa "const unsigned char **der_in" 104.Fa "long length" 105.Fc 106.Ft int 107.Fo i2d_ASN1_ENUMERATED 108.Fa "ASN1_ENUMERATED *val_in" 109.Fa "unsigned char **der_out" 110.Fc 111.Ft ASN1_UTF8STRING * 112.Fo d2i_ASN1_UTF8STRING 113.Fa "ASN1_UTF8STRING **val_out" 114.Fa "const unsigned char **der_in" 115.Fa "long length" 116.Fc 117.Ft int 118.Fo i2d_ASN1_UTF8STRING 119.Fa "ASN1_UTF8STRING *val_in" 120.Fa "unsigned char **der_out" 121.Fc 122.Ft ASN1_IA5STRING * 123.Fo d2i_ASN1_IA5STRING 124.Fa "ASN1_IA5STRING **val_out" 125.Fa "const unsigned char **der_in" 126.Fa "long length" 127.Fc 128.Ft int 129.Fo i2d_ASN1_IA5STRING 130.Fa "ASN1_IA5STRING *val_in" 131.Fa "unsigned char **der_out" 132.Fc 133.Ft ASN1_UNIVERSALSTRING * 134.Fo d2i_ASN1_UNIVERSALSTRING 135.Fa "ASN1_UNIVERSALSTRING **val_out" 136.Fa "const unsigned char **der_in" 137.Fa "long length" 138.Fc 139.Ft int 140.Fo i2d_ASN1_UNIVERSALSTRING 141.Fa "ASN1_UNIVERSALSTRING *val_in" 142.Fa "unsigned char **der_out" 143.Fc 144.Ft ASN1_BMPSTRING * 145.Fo d2i_ASN1_BMPSTRING 146.Fa "ASN1_BMPSTRING **val_out" 147.Fa "const unsigned char **der_in" 148.Fa "long length" 149.Fc 150.Ft int 151.Fo i2d_ASN1_BMPSTRING 152.Fa "ASN1_BMPSTRING *val_in" 153.Fa "unsigned char **der_out" 154.Fc 155.Ft ASN1_GENERALSTRING * 156.Fo d2i_ASN1_GENERALSTRING 157.Fa "ASN1_GENERALSTRING **val_out" 158.Fa "const unsigned char **der_in" 159.Fa "long length" 160.Fc 161.Ft int 162.Fo i2d_ASN1_GENERALSTRING 163.Fa "ASN1_GENERALSTRING *val_in" 164.Fa "unsigned char **der_out" 165.Fc 166.Ft ASN1_T61STRING * 167.Fo d2i_ASN1_T61STRING 168.Fa "ASN1_T61STRING **val_out" 169.Fa "const unsigned char **der_in" 170.Fa "long length" 171.Fc 172.Ft int 173.Fo i2d_ASN1_T61STRING 174.Fa "ASN1_T61STRING *val_in" 175.Fa "unsigned char **der_out" 176.Fc 177.Ft ASN1_VISIBLESTRING * 178.Fo d2i_ASN1_VISIBLESTRING 179.Fa "ASN1_VISIBLESTRING **val_out" 180.Fa "const unsigned char **der_in" 181.Fa "long length" 182.Fc 183.Ft int 184.Fo i2d_ASN1_VISIBLESTRING 185.Fa "ASN1_VISIBLESTRING *val_in" 186.Fa "unsigned char **der_out" 187.Fc 188.Ft ASN1_PRINTABLESTRING * 189.Fo d2i_ASN1_PRINTABLESTRING 190.Fa "ASN1_PRINTABLESTRING **val_out" 191.Fa "const unsigned char **der_in" 192.Fa "long length" 193.Fc 194.Ft int 195.Fo i2d_ASN1_PRINTABLESTRING 196.Fa "ASN1_PRINTABLESTRING *val_in" 197.Fa "unsigned char **der_out" 198.Fc 199.Ft ASN1_STRING * 200.Fo d2i_ASN1_PRINTABLE 201.Fa "ASN1_STRING **val_out" 202.Fa "const unsigned char **der_in" 203.Fa "long length" 204.Fc 205.Ft int 206.Fo i2d_ASN1_PRINTABLE 207.Fa "ASN1_STRING *val_in" 208.Fa "unsigned char **der_out" 209.Fc 210.Ft ASN1_STRING * 211.Fo d2i_DIRECTORYSTRING 212.Fa "ASN1_STRING **val_out" 213.Fa "const unsigned char **der_in" 214.Fa "long length" 215.Fc 216.Ft int 217.Fo i2d_DIRECTORYSTRING 218.Fa "ASN1_STRING *val_in" 219.Fa "unsigned char **der_out" 220.Fc 221.Ft ASN1_STRING * 222.Fo d2i_DISPLAYTEXT 223.Fa "ASN1_STRING **val_out" 224.Fa "const unsigned char **der_in" 225.Fa "long length" 226.Fc 227.Ft int 228.Fo i2d_DISPLAYTEXT 229.Fa "ASN1_STRING *val_in" 230.Fa "unsigned char **der_out" 231.Fc 232.Ft ASN1_GENERALIZEDTIME * 233.Fo d2i_ASN1_GENERALIZEDTIME 234.Fa "ASN1_GENERALIZEDTIME **val_out" 235.Fa "const unsigned char **der_in" 236.Fa "long length" 237.Fc 238.Ft int 239.Fo i2d_ASN1_GENERALIZEDTIME 240.Fa "ASN1_GENERALIZEDTIME *val_in" 241.Fa "unsigned char **der_out" 242.Fc 243.Ft ASN1_UTCTIME * 244.Fo d2i_ASN1_UTCTIME 245.Fa "ASN1_UTCTIME **val_out" 246.Fa "const unsigned char **der_in" 247.Fa "long length" 248.Fc 249.Ft int 250.Fo i2d_ASN1_UTCTIME 251.Fa "ASN1_UTCTIME *val_in" 252.Fa "unsigned char **der_out" 253.Fc 254.Ft ASN1_TIME * 255.Fo d2i_ASN1_TIME 256.Fa "ASN1_TIME **val_out" 257.Fa "const unsigned char **der_in" 258.Fa "long length" 259.Fc 260.Ft int 261.Fo i2d_ASN1_TIME 262.Fa "ASN1_TIME *val_in" 263.Fa "unsigned char **der_out" 264.Fc 265.Sh DESCRIPTION 266These functions decode and encode various ASN.1 built-in types 267that can be represented by 268.Vt ASN1_STRING 269objects. 270For details about the semantics, examples, caveats, and bugs, see 271.Xr ASN1_item_d2i 3 . 272.Pp 273The format consists of one identifier byte, one or more length bytes, 274and one or more content bytes. 275The identifier bytes and corresponding ASN.1 types are as follows: 276.Bl -column ASN1_GENERALIZEDTIME identifier 277.It Em OpenSSL type Ta Em identifier Ta Em ASN.1 type 278.It Ta 279.It Vt ASN1_OCTET_STRING Ta 0x04 Ta OCTET STRING 280.It Vt ASN1_BIT_STRING Ta 0x03 Ta BIT STRING 281.It Vt ASN1_INTEGER Ta 0x02 Ta INTEGER 282.It Vt ASN1_ENUMERATED Ta 0x0a Ta ENUMERATED 283.It Vt ASN1_UTF8STRING Ta 0x0c Ta UTF8String 284.It Vt ASN1_IA5STRING Ta 0x16 Ta IA5String 285.It Vt ASN1_UNIVERSALSTRING Ta 0x1c Ta UniversalString 286.It Vt ASN1_BMPSTRING Ta 0x1e Ta BMPString 287.It Vt ASN1_GENERALSTRING Ta 0x1b Ta GeneralString 288.It Vt ASN1_T61STRING Ta 0x14 Ta T61String 289.It Vt ASN1_VISIBLESTRING Ta 0x1a Ta VisibleString 290.It Vt ASN1_PRINTABLESTRING Ta 0x13 Ta PrintableString 291.It Vt ASN1_GENERALIZEDTIME Ta 0x18 Ta GeneralizedTime 292.It Vt ASN1_UTCTIME Ta 0x17 Ta UTCTime 293.El 294.Pp 295.Fn d2i_DIRECTORYSTRING 296and 297.Fn i2d_DIRECTORYSTRING 298decode and encode an ASN.1 299.Vt DirectoryString 300structure defined in RFC 5280 section 4.1.2.4 301and used for ASN.1 302.Vt EDIPartyName 303structures; see 304.Xr EDIPARTYNAME_new 3 . 305When decoding, it accepts any of the types UTF8String, UniversalString, 306BMPString, T61String, or PrintableString. 307When encoding, 308it writes out the character string type that is actually passed in. 309.Pp 310.Fn d2i_ASN1_PRINTABLE 311and 312.Fn i2d_ASN1_PRINTABLE 313are non-standard variants of 314.Fn d2i_DIRECTORYSTRING 315and 316.Fn i2d_DIRECTORYSTRING 317that also accept IA5String, NumericString, BIT STRING, and SEQUENCE 318ASN.1 values as well as ASN.1 values with unknown identifier 319bytes (0x07, 0x08, 0x09, 0x0b, 0x0d, 0x0e, 0x0f, 0x1d, and 0x1f). 320Even though the standard requires the use of 321.Vt DirectoryString 322in the relative distinguished names described in 323.Xr X509_NAME_ENTRY_new 3 , 324the library accepts this wider range of choices. 325.Pp 326.Fn d2i_DISPLAYTEXT 327and 328.Fn i2d_DISPLAYTEXT 329decode and encode an ASN.1 330.Vt DisplayText 331structure defined in RFC 5280 section 4.2.1.4 332and used for ASN.1 333.Vt UserNotice 334structures in certificate policies; see 335.Xr USERNOTICE_new 3 . 336When decoding, it accepts any of the types UTF8String, IA5String, 337BMPString, or VisibleString. 338When encoding, 339it writes out the character string type that is actually passed in. 340.Pp 341.Fn d2i_ASN1_TIME 342and 343.Fn i2d_ASN1_TIME 344decode and encode an ASN.1 345.Vt Time 346structure defined in RFC 5280 section 4.1 347and used for ASN.1 348.Vt Validity 349structures in certificates; see 350.Xr X509_VAL_new 3 . 351They are also used for certificate revocation lists; see 352.Xr X509_CRL_INFO_new 3 . 353When decoding, it accepts either GeneralizedTime or UTCTime. 354When encoding, it writes out the time type that is actually passed in. 355.Pp 356The following constants describe the ASN.1 tags that are valid 357when decoding with the above functions. 358See 359.Xr ASN1_tag2bit 3 360for more details about the 361.Dv B_ASN1_* 362constants. 363.Bl -column d2i_DIRECTORYSTRING() B_ASN1_DIRECTORYSTRING -offset indent 364.It decoding function Ta mask constant 365.It Fn d2i_DIRECTORYSTRING Ta Dv B_ASN1_DIRECTORYSTRING 366.It Fn d2i_ASN1_PRINTABLE Ta Dv B_ASN1_PRINTABLE 367.It Fn d2i_DISPLAYTEXT Ta Dv B_ASN1_DISPLAYTEXT 368.It Fn d2i_ASN1_TIME Ta Dv B_ASN1_TIME 369.El 370.Pp 371.Fn d2i_ASN1_UINTEGER 372is similar to 373.Fn d2i_ASN1_INTEGER 374except that it ignores the sign bit in the BER encoding and treats 375all integers as positive. 376It helps to process BER input produced by broken software 377that neglects adding a leading NUL content byte where required. 378.Sh RETURN VALUES 379The 380.Fn d2i_* 381decoding functions return an 382.Vt ASN1_STRING 383object or 384.Dv NULL 385if an error occurs. 386.Pp 387The 388.Fn i2d_* 389encoding functions return the number of bytes successfully encoded 390or a negative value if an error occurs. 391.Sh SEE ALSO 392.Xr ASN1_item_d2i 3 , 393.Xr ASN1_STRING_new 3 394.Sh STANDARDS 395ITU-T Recommendation X.680, also known as ISO/IEC 8824-1: 396Information technology - Abstract Syntax Notation One (ASN.1): 397Specification of basic notation 398.Pp 399RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 400Certificate Revocation List (CRL) Profile 401.Sh HISTORY 402.Fn d2i_ASN1_OCTET_STRING , 403.Fn i2d_ASN1_OCTET_STRING , 404.Fn d2i_ASN1_BIT_STRING , 405.Fn i2d_ASN1_BIT_STRING , 406.Fn d2i_ASN1_INTEGER , 407.Fn i2d_ASN1_INTEGER , 408.Fn d2i_ASN1_IA5STRING , 409.Fn i2d_ASN1_IA5STRING , 410.Fn d2i_ASN1_T61STRING , 411.Fn i2d_ASN1_T61STRING , 412.Fn d2i_ASN1_PRINTABLESTRING , 413.Fn i2d_ASN1_PRINTABLESTRING , 414.Fn d2i_ASN1_PRINTABLE , 415.Fn i2d_ASN1_PRINTABLE , 416.Fn d2i_ASN1_UTCTIME , 417and 418.Fn i2d_ASN1_UTCTIME 419first appeared in SSLeay 0.5.1 and have been available since 420.Ox 2.4 . 421.Pp 422.Fn d2i_ASN1_BMPSTRING 423and 424.Fn i2d_ASN1_BMPSTRING 425first appeared in SSLeay 0.9.1. 426.Fn d2i_ASN1_ENUMERATED , 427.Fn i2d_ASN1_ENUMERATED , 428.Fn d2i_ASN1_GENERALIZEDTIME , 429.Fn i2d_ASN1_GENERALIZEDTIME , 430.Fn d2i_ASN1_TIME , 431and 432.Fn i2d_ASN1_TIME 433first appeared in OpenSSL 0.9.2b. 434.Fn d2i_ASN1_UINTEGER , 435.Fn d2i_ASN1_UTF8STRING , 436.Fn i2d_ASN1_UTF8STRING , 437.Fn d2i_ASN1_VISIBLESTRING , 438.Fn i2d_ASN1_VISIBLESTRING , 439.Fn d2i_DIRECTORYSTRING , 440.Fn i2d_DIRECTORYSTRING , 441.Fn d2i_DISPLAYTEXT 442and 443.Fn i2d_DISPLAYTEXT 444first appeared in OpenSSL 0.9.3. 445These functions have been available since 446.Ox 2.6 . 447.Pp 448.Fn d2i_ASN1_UNIVERSALSTRING , 449.Fn i2d_ASN1_UNIVERSALSTRING , 450.Fn d2i_ASN1_GENERALSTRING , 451and 452.Fn i2d_ASN1_GENERALSTRING 453first appeared in OpenSSL 0.9.7 and have been available since 454.Ox 3.2 . 455.Sh CAVEATS 456Other implementations may accept or emit invalid DER encodings of 457GeneralizedTime and UTCTime. 458Portable applications should use 459.Fn ASN1_STRING_length 460to double check whether a given GeneralizedTime or UTCTime object is at least 46115 or 13 bytes, respectively. 462