1.\" $OpenBSD: d2i_ASN1_OCTET_STRING.3,v 1.12 2018/03/27 17:35:50 schwarze 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: March 27 2018 $ 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 octet, 274one or more length octets, 275and one or more content octets. 276The identifier octets and corresponding ASN.1 types are as follows: 277.Bl -column ASN1_GENERALIZEDTIME identifier 278.It Em OpenSSL type Ta Em identifier Ta Em ASN.1 type 279.It Ta 280.It Vt ASN1_OCTET_STRING Ta 0x04 Ta OCTET STRING 281.It Vt ASN1_BIT_STRING Ta 0x03 Ta BIT STRING 282.It Vt ASN1_INTEGER Ta 0x02 Ta INTEGER 283.It Vt ASN1_ENUMERATED Ta 0x0a Ta ENUMERATED 284.It Vt ASN1_UTF8STRING Ta 0x0c Ta UTF8String 285.It Vt ASN1_IA5STRING Ta 0x16 Ta IA5String 286.It Vt ASN1_UNIVERSALSTRING Ta 0x1c Ta UniversalString 287.It Vt ASN1_BMPSTRING Ta 0x1e Ta BMPString 288.It Vt ASN1_GENERALSTRING Ta 0x1b Ta GeneralString 289.It Vt ASN1_T61STRING Ta 0x14 Ta T61String 290.It Vt ASN1_VISIBLESTRING Ta 0x1a Ta VisibleString 291.It Vt ASN1_PRINTABLESTRING Ta 0x13 Ta PrintableString 292.It Vt ASN1_GENERALIZEDTIME Ta 0x18 Ta GeneralizedTime 293.It Vt ASN1_UTCTIME Ta 0x17 Ta UTCTime 294.El 295.Pp 296.Fn d2i_DIRECTORYSTRING 297and 298.Fn i2d_DIRECTORYSTRING 299decode and encode an ASN.1 300.Vt DirectoryString 301structure defined in RFC 5280 section 4.1.2.4 302and used for ASN.1 303.Vt EDIPartyName 304structures; see 305.Xr EDIPARTYNAME_new 3 . 306When decoding, it accepts any of the types UTF8String, UniversalString, 307BMPString, T61String, or PrintableString. 308When encoding, 309it writes out the character string type that is actually passed in. 310.Pp 311.Fn d2i_ASN1_PRINTABLE 312and 313.Fn i2d_ASN1_PRINTABLE 314are non-standard variants of 315.Fn d2i_DIRECTORYSTRING 316and 317.Fn i2d_DIRECTORYSTRING 318that also accept IA5String, NumericString, BIT STRING, and SEQUENCE 319ASN.1 values as well as ASN.1 values with unknown identifier 320octets (0x07, 0x08, 0x09, 0x0b, 0x0d, 0x0e, 0x0f, 0x1d, and 0x1f). 321Even though the standard requires the use of 322.Vt DirectoryString 323in the relative distinguished names described in 324.Xr X509_NAME_ENTRY_new 3 , 325the library accepts this wider range of choices. 326.Pp 327.Fn d2i_DISPLAYTEXT 328and 329.Fn i2d_DISPLAYTEXT 330decode and encode an ASN.1 331.Vt DisplayText 332structure defined in RFC 5280 section 4.2.1.4 333and used for ASN.1 334.Vt UserNotice 335structures in certificate policies; see 336.Xr USERNOTICE_new 3 . 337When decoding, it accepts any of the types UTF8String, IA5String, 338BMPString, or VisibleString. 339When encoding, 340it writes out the character string type that is actually passed in. 341.Pp 342.Fn d2i_ASN1_TIME 343and 344.Fn i2d_ASN1_TIME 345decode and encode an ASN.1 346.Vt Time 347structure defined in RFC 5280 section 4.1 348and used for ASN.1 349.Vt Validity 350structures in certificates; see 351.Xr X509_VAL_new 3 . 352They are also used for certificate revocation lists; see 353.Xr X509_CRL_INFO_new 3 . 354When decoding, it accepts either GeneralizedTime or UTCTime. 355When encoding, it writes out the time type that is actually passed in. 356.Pp 357.Fn d2i_ASN1_UINTEGER 358is similar to 359.Fn d2i_ASN1_INTEGER 360except that it ignores the sign bit in the BER encoding and treats 361all integers as positive. 362It helps to process BER input produced by broken software 363that neglects adding a leading NUL content byte where required. 364.Sh RETURN VALUES 365The 366.Fn d2i_* 367decoding functions return an 368.Vt ASN1_STRING 369object or 370.Dv NULL 371if an error occurs. 372.Pp 373The 374.Fn i2d_* 375encoding functions return the number of bytes successfully encoded 376or a negative value if an error occurs. 377.Sh SEE ALSO 378.Xr ASN1_item_d2i 3 , 379.Xr ASN1_STRING_new 3 380.Sh STANDARDS 381ITU-T Recommendation X.680, also known as ISO/IEC 8824-1: 382Information technology - Abstract Syntax Notation One (ASN.1): 383Specification of basic notation 384.Pp 385RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 386Certificate Revocation List (CRL) Profile 387.Sh HISTORY 388.Fn d2i_ASN1_OCTET_STRING , 389.Fn i2d_ASN1_OCTET_STRING , 390.Fn d2i_ASN1_BIT_STRING , 391.Fn i2d_ASN1_BIT_STRING , 392.Fn d2i_ASN1_INTEGER , 393.Fn i2d_ASN1_INTEGER , 394.Fn d2i_ASN1_IA5STRING , 395.Fn i2d_ASN1_IA5STRING , 396.Fn d2i_ASN1_T61STRING , 397.Fn i2d_ASN1_T61STRING , 398.Fn d2i_ASN1_PRINTABLESTRING , 399.Fn i2d_ASN1_PRINTABLESTRING 400.Fn d2i_ASN1_PRINTABLE , 401.Fn i2d_ASN1_PRINTABLE , 402.Fn d2i_ASN1_UTCTIME , 403and 404.Fn i2d_ASN1_UTCTIME 405first appeared in SSLeay 0.5.1 and have been available since 406.Ox 2.4 . 407.Pp 408.Fn d2i_ASN1_BMPSTRING 409and 410.Fn i2d_ASN1_BMPSTRING 411first appeared in SSLeay 0.9.1. 412.Fn d2i_ASN1_ENUMERATED , 413.Fn i2d_ASN1_ENUMERATED , 414.Fn d2i_ASN1_GENERALIZEDTIME , 415.Fn i2d_ASN1_GENERALIZEDTIME , 416.Fn d2i_ASN1_TIME , 417and 418.Fn i2d_ASN1_TIME 419first appeared in OpenSSL 0.9.2b. 420.Fn d2i_ASN1_UINTEGER , 421.Fn d2i_ASN1_UTF8STRING , 422.Fn i2d_ASN1_UTF8STRING , 423.Fn d2i_ASN1_VISIBLESTRING , 424.Fn i2d_ASN1_VISIBLESTRING , 425.Fn d2i_DIRECTORYSTRING , 426.Fn i2d_DIRECTORYSTRING , 427.Fn d2i_DISPLAYTEXT 428and 429.Fn i2d_DISPLAYTEXT 430first appeared in OpenSSL 0.9.3. 431These functions have been available since 432.Ox 2.6 . 433.Pp 434.Fn d2i_ASN1_UNIVERSALSTRING , 435.Fn i2d_ASN1_UNIVERSALSTRING , 436.Fn d2i_ASN1_GENERALSTRING , 437and 438.Fn i2d_ASN1_GENERALSTRING 439first appeared in OpenSSL 0.9.7 and have been available since 440.Ox 3.2 . 441