.\" $OpenBSD: d2i_ASN1_OCTET_STRING.3,v 1.20 2024/02/13 12:38:43 job Exp $ .\" .\" Copyright (c) 2017 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd $Mdocdate: February 13 2024 $ .Dt D2I_ASN1_OCTET_STRING 3 .Os .Sh NAME .Nm d2i_ASN1_OCTET_STRING , .Nm i2d_ASN1_OCTET_STRING , .Nm d2i_ASN1_BIT_STRING , .Nm i2d_ASN1_BIT_STRING , .Nm d2i_ASN1_INTEGER , .Nm i2d_ASN1_INTEGER , .Nm d2i_ASN1_UINTEGER , .Nm d2i_ASN1_ENUMERATED , .Nm i2d_ASN1_ENUMERATED , .Nm d2i_ASN1_UTF8STRING , .Nm i2d_ASN1_UTF8STRING , .Nm d2i_ASN1_IA5STRING , .Nm i2d_ASN1_IA5STRING , .Nm d2i_ASN1_UNIVERSALSTRING , .Nm i2d_ASN1_UNIVERSALSTRING , .Nm d2i_ASN1_BMPSTRING , .Nm i2d_ASN1_BMPSTRING , .Nm d2i_ASN1_GENERALSTRING , .Nm i2d_ASN1_GENERALSTRING , .Nm d2i_ASN1_T61STRING , .Nm i2d_ASN1_T61STRING , .Nm d2i_ASN1_VISIBLESTRING , .Nm i2d_ASN1_VISIBLESTRING , .Nm d2i_ASN1_PRINTABLESTRING , .Nm i2d_ASN1_PRINTABLESTRING , .Nm d2i_ASN1_PRINTABLE , .Nm i2d_ASN1_PRINTABLE , .Nm d2i_DIRECTORYSTRING , .Nm i2d_DIRECTORYSTRING , .Nm d2i_DISPLAYTEXT , .Nm i2d_DISPLAYTEXT , .Nm d2i_ASN1_GENERALIZEDTIME , .Nm i2d_ASN1_GENERALIZEDTIME , .Nm d2i_ASN1_UTCTIME , .Nm i2d_ASN1_UTCTIME , .Nm d2i_ASN1_TIME , .Nm i2d_ASN1_TIME .Nd decode and encode ASN1_STRING objects .Sh SYNOPSIS .In openssl/asn1.h .Ft ASN1_OCTET_STRING * .Fo d2i_ASN1_OCTET_STRING .Fa "ASN1_OCTET_STRING **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_OCTET_STRING .Fa "ASN1_OCTET_STRING *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_BIT_STRING * .Fo d2i_ASN1_BIT_STRING .Fa "ASN1_BIT_STRING **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_BIT_STRING .Fa "ASN1_BIT_STRING *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_INTEGER * .Fo d2i_ASN1_INTEGER .Fa "ASN1_INTEGER **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_INTEGER .Fa "ASN1_INTEGER *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_INTEGER * .Fo d2i_ASN1_UINTEGER .Fa "ASN1_INTEGER **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft ASN1_ENUMERATED * .Fo d2i_ASN1_ENUMERATED .Fa "ASN1_ENUMERATED **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_ENUMERATED .Fa "ASN1_ENUMERATED *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_UTF8STRING * .Fo d2i_ASN1_UTF8STRING .Fa "ASN1_UTF8STRING **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_UTF8STRING .Fa "ASN1_UTF8STRING *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_IA5STRING * .Fo d2i_ASN1_IA5STRING .Fa "ASN1_IA5STRING **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_IA5STRING .Fa "ASN1_IA5STRING *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_UNIVERSALSTRING * .Fo d2i_ASN1_UNIVERSALSTRING .Fa "ASN1_UNIVERSALSTRING **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_UNIVERSALSTRING .Fa "ASN1_UNIVERSALSTRING *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_BMPSTRING * .Fo d2i_ASN1_BMPSTRING .Fa "ASN1_BMPSTRING **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_BMPSTRING .Fa "ASN1_BMPSTRING *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_GENERALSTRING * .Fo d2i_ASN1_GENERALSTRING .Fa "ASN1_GENERALSTRING **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_GENERALSTRING .Fa "ASN1_GENERALSTRING *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_T61STRING * .Fo d2i_ASN1_T61STRING .Fa "ASN1_T61STRING **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_T61STRING .Fa "ASN1_T61STRING *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_VISIBLESTRING * .Fo d2i_ASN1_VISIBLESTRING .Fa "ASN1_VISIBLESTRING **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_VISIBLESTRING .Fa "ASN1_VISIBLESTRING *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_PRINTABLESTRING * .Fo d2i_ASN1_PRINTABLESTRING .Fa "ASN1_PRINTABLESTRING **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_PRINTABLESTRING .Fa "ASN1_PRINTABLESTRING *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_STRING * .Fo d2i_ASN1_PRINTABLE .Fa "ASN1_STRING **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_PRINTABLE .Fa "ASN1_STRING *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_STRING * .Fo d2i_DIRECTORYSTRING .Fa "ASN1_STRING **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_DIRECTORYSTRING .Fa "ASN1_STRING *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_STRING * .Fo d2i_DISPLAYTEXT .Fa "ASN1_STRING **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_DISPLAYTEXT .Fa "ASN1_STRING *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_GENERALIZEDTIME * .Fo d2i_ASN1_GENERALIZEDTIME .Fa "ASN1_GENERALIZEDTIME **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_GENERALIZEDTIME .Fa "ASN1_GENERALIZEDTIME *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_UTCTIME * .Fo d2i_ASN1_UTCTIME .Fa "ASN1_UTCTIME **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_UTCTIME .Fa "ASN1_UTCTIME *val_in" .Fa "unsigned char **der_out" .Fc .Ft ASN1_TIME * .Fo d2i_ASN1_TIME .Fa "ASN1_TIME **val_out" .Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_ASN1_TIME .Fa "ASN1_TIME *val_in" .Fa "unsigned char **der_out" .Fc .Sh DESCRIPTION These functions decode and encode various ASN.1 built-in types that can be represented by .Vt ASN1_STRING objects. For details about the semantics, examples, caveats, and bugs, see .Xr ASN1_item_d2i 3 . .Pp The format consists of one identifier byte, one or more length bytes, and one or more content bytes. The identifier bytes and corresponding ASN.1 types are as follows: .Bl -column ASN1_GENERALIZEDTIME identifier .It Em OpenSSL type Ta Em identifier Ta Em ASN.1 type .It Ta .It Vt ASN1_OCTET_STRING Ta 0x04 Ta OCTET STRING .It Vt ASN1_BIT_STRING Ta 0x03 Ta BIT STRING .It Vt ASN1_INTEGER Ta 0x02 Ta INTEGER .It Vt ASN1_ENUMERATED Ta 0x0a Ta ENUMERATED .It Vt ASN1_UTF8STRING Ta 0x0c Ta UTF8String .It Vt ASN1_IA5STRING Ta 0x16 Ta IA5String .It Vt ASN1_UNIVERSALSTRING Ta 0x1c Ta UniversalString .It Vt ASN1_BMPSTRING Ta 0x1e Ta BMPString .It Vt ASN1_GENERALSTRING Ta 0x1b Ta GeneralString .It Vt ASN1_T61STRING Ta 0x14 Ta T61String .It Vt ASN1_VISIBLESTRING Ta 0x1a Ta VisibleString .It Vt ASN1_PRINTABLESTRING Ta 0x13 Ta PrintableString .It Vt ASN1_GENERALIZEDTIME Ta 0x18 Ta GeneralizedTime .It Vt ASN1_UTCTIME Ta 0x17 Ta UTCTime .El .Pp .Fn d2i_DIRECTORYSTRING and .Fn i2d_DIRECTORYSTRING decode and encode an ASN.1 .Vt DirectoryString structure defined in RFC 5280 section 4.1.2.4 and used for ASN.1 .Vt EDIPartyName structures; see .Xr EDIPARTYNAME_new 3 . When decoding, it accepts any of the types UTF8String, UniversalString, BMPString, T61String, or PrintableString. When encoding, it writes out the character string type that is actually passed in. .Pp .Fn d2i_ASN1_PRINTABLE and .Fn i2d_ASN1_PRINTABLE are non-standard variants of .Fn d2i_DIRECTORYSTRING and .Fn i2d_DIRECTORYSTRING that also accept IA5String, NumericString, BIT STRING, and SEQUENCE ASN.1 values as well as ASN.1 values with unknown identifier bytes (0x07, 0x08, 0x09, 0x0b, 0x0d, 0x0e, 0x0f, 0x1d, and 0x1f). Even though the standard requires the use of .Vt DirectoryString in the relative distinguished names described in .Xr X509_NAME_ENTRY_new 3 , the library accepts this wider range of choices. .Pp .Fn d2i_DISPLAYTEXT and .Fn i2d_DISPLAYTEXT decode and encode an ASN.1 .Vt DisplayText structure defined in RFC 5280 section 4.2.1.4 and used for ASN.1 .Vt UserNotice structures in certificate policies; see .Xr USERNOTICE_new 3 . When decoding, it accepts any of the types UTF8String, IA5String, BMPString, or VisibleString. When encoding, it writes out the character string type that is actually passed in. .Pp .Fn d2i_ASN1_TIME and .Fn i2d_ASN1_TIME decode and encode an ASN.1 .Vt Time structure defined in RFC 5280 section 4.1 and used for ASN.1 .Vt Validity structures in certificates; see .Xr X509_VAL_new 3 . They are also used for certificate revocation lists; see .Xr X509_CRL_INFO_new 3 . When decoding, it accepts either GeneralizedTime or UTCTime. When encoding, it writes out the time type that is actually passed in. .Pp The following constants describe the ASN.1 tags that are valid when decoding with the above functions. See .Xr ASN1_tag2bit 3 for more details about the .Dv B_ASN1_* constants. .Bl -column d2i_DIRECTORYSTRING() B_ASN1_DIRECTORYSTRING -offset indent .It decoding function Ta mask constant .It Fn d2i_DIRECTORYSTRING Ta Dv B_ASN1_DIRECTORYSTRING .It Fn d2i_ASN1_PRINTABLE Ta Dv B_ASN1_PRINTABLE .It Fn d2i_DISPLAYTEXT Ta Dv B_ASN1_DISPLAYTEXT .It Fn d2i_ASN1_TIME Ta Dv B_ASN1_TIME .El .Pp .Fn d2i_ASN1_UINTEGER is similar to .Fn d2i_ASN1_INTEGER except that it ignores the sign bit in the BER encoding and treats all integers as positive. It helps to process BER input produced by broken software that neglects adding a leading NUL content byte where required. .Sh RETURN VALUES The .Fn d2i_* decoding functions return an .Vt ASN1_STRING object or .Dv NULL if an error occurs. .Pp The .Fn i2d_* encoding functions return the number of bytes successfully encoded or a negative value if an error occurs. .Sh SEE ALSO .Xr ASN1_item_d2i 3 , .Xr ASN1_STRING_new 3 .Sh STANDARDS ITU-T Recommendation X.680, also known as ISO/IEC 8824-1: Information technology - Abstract Syntax Notation One (ASN.1): Specification of basic notation .Pp RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile .Sh HISTORY .Fn d2i_ASN1_OCTET_STRING , .Fn i2d_ASN1_OCTET_STRING , .Fn d2i_ASN1_BIT_STRING , .Fn i2d_ASN1_BIT_STRING , .Fn d2i_ASN1_INTEGER , .Fn i2d_ASN1_INTEGER , .Fn d2i_ASN1_IA5STRING , .Fn i2d_ASN1_IA5STRING , .Fn d2i_ASN1_T61STRING , .Fn i2d_ASN1_T61STRING , .Fn d2i_ASN1_PRINTABLESTRING , .Fn i2d_ASN1_PRINTABLESTRING , .Fn d2i_ASN1_PRINTABLE , .Fn i2d_ASN1_PRINTABLE , .Fn d2i_ASN1_UTCTIME , and .Fn i2d_ASN1_UTCTIME first appeared in SSLeay 0.5.1 and have been available since .Ox 2.4 . .Pp .Fn d2i_ASN1_BMPSTRING and .Fn i2d_ASN1_BMPSTRING first appeared in SSLeay 0.9.1. .Fn d2i_ASN1_ENUMERATED , .Fn i2d_ASN1_ENUMERATED , .Fn d2i_ASN1_GENERALIZEDTIME , .Fn i2d_ASN1_GENERALIZEDTIME , .Fn d2i_ASN1_TIME , and .Fn i2d_ASN1_TIME first appeared in OpenSSL 0.9.2b. .Fn d2i_ASN1_UINTEGER , .Fn d2i_ASN1_UTF8STRING , .Fn i2d_ASN1_UTF8STRING , .Fn d2i_ASN1_VISIBLESTRING , .Fn i2d_ASN1_VISIBLESTRING , .Fn d2i_DIRECTORYSTRING , .Fn i2d_DIRECTORYSTRING , .Fn d2i_DISPLAYTEXT and .Fn i2d_DISPLAYTEXT first appeared in OpenSSL 0.9.3. These functions have been available since .Ox 2.6 . .Pp .Fn d2i_ASN1_UNIVERSALSTRING , .Fn i2d_ASN1_UNIVERSALSTRING , .Fn d2i_ASN1_GENERALSTRING , and .Fn i2d_ASN1_GENERALSTRING first appeared in OpenSSL 0.9.7 and have been available since .Ox 3.2 . .Sh CAVEATS Other implementations may accept or emit invalid DER encodings of GeneralizedTime and UTCTime. Portable applications should use .Fn ASN1_STRING_length to double check whether a given GeneralizedTime or UTCTime object is at least 15 or 13 bytes, respectively.