D2I_ASN1_OCTET_STRING(3) | Library Functions Manual | D2I_ASN1_OCTET_STRING(3)

# NAME

`d2i_ASN1_OCTET_STRING`, `i2d_ASN1_OCTET_STRING`, `d2i_ASN1_BIT_STRING`, `i2d_ASN1_BIT_STRING`, `d2i_ASN1_INTEGER`, `i2d_ASN1_INTEGER`, `d2i_ASN1_UINTEGER`, `d2i_ASN1_ENUMERATED`, `i2d_ASN1_ENUMERATED`, `d2i_ASN1_UTF8STRING`, `i2d_ASN1_UTF8STRING`, `d2i_ASN1_IA5STRING`, `i2d_ASN1_IA5STRING`, `d2i_ASN1_UNIVERSALSTRING`, `i2d_ASN1_UNIVERSALSTRING`, `d2i_ASN1_BMPSTRING`, `i2d_ASN1_BMPSTRING`, `d2i_ASN1_GENERALSTRING`, `i2d_ASN1_GENERALSTRING`, `d2i_ASN1_T61STRING`, `i2d_ASN1_T61STRING`, `d2i_ASN1_VISIBLESTRING`, `i2d_ASN1_VISIBLESTRING`, `d2i_ASN1_PRINTABLESTRING`, `i2d_ASN1_PRINTABLESTRING`, `d2i_ASN1_PRINTABLE`, `i2d_ASN1_PRINTABLE`, `d2i_DIRECTORYSTRING`, `i2d_DIRECTORYSTRING`, `d2i_DISPLAYTEXT`, `i2d_DISPLAYTEXT`, `d2i_ASN1_GENERALIZEDTIME`, `i2d_ASN1_GENERALIZEDTIME`, `d2i_ASN1_UTCTIME`, `i2d_ASN1_UTCTIME`, `d2i_ASN1_TIME`, `i2d_ASN1_TIME` — decode and encode ASN1_STRING objects

# SYNOPSIS

library “libcrypto”
`#include <openssl/asn1.h>`

ASN1_OCTET_STRING *
`d2i_ASN1_OCTET_STRING`(ASN1_OCTET_STRING **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_OCTET_STRING`(ASN1_OCTET_STRING *val_in, unsigned char **der_out);

ASN1_BIT_STRING *
`d2i_ASN1_BIT_STRING`(ASN1_BIT_STRING **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_BIT_STRING`(ASN1_BIT_STRING *val_in, unsigned char **der_out);

ASN1_INTEGER *
`d2i_ASN1_INTEGER`(ASN1_INTEGER **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_INTEGER`(ASN1_INTEGER *val_in, unsigned char **der_out);

ASN1_INTEGER *
`d2i_ASN1_UINTEGER`(ASN1_INTEGER **val_out, const unsigned char **der_in, long length);

ASN1_ENUMERATED *
`d2i_ASN1_ENUMERATED`(ASN1_ENUMERATED **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_ENUMERATED`(ASN1_ENUMERATED *val_in, unsigned char **der_out);

ASN1_UTF8STRING *
`d2i_ASN1_UTF8STRING`(ASN1_UTF8STRING **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_UTF8STRING`(ASN1_UTF8STRING *val_in, unsigned char **der_out);

ASN1_IA5STRING *
`d2i_ASN1_IA5STRING`(ASN1_IA5STRING **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_IA5STRING`(ASN1_IA5STRING *val_in, unsigned char **der_out);

ASN1_UNIVERSALSTRING *
`d2i_ASN1_UNIVERSALSTRING`(ASN1_UNIVERSALSTRING **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_UNIVERSALSTRING`(ASN1_UNIVERSALSTRING *val_in, unsigned char **der_out);

ASN1_BMPSTRING *
`d2i_ASN1_BMPSTRING`(ASN1_BMPSTRING **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_BMPSTRING`(ASN1_BMPSTRING *val_in, unsigned char **der_out);

ASN1_GENERALSTRING *
`d2i_ASN1_GENERALSTRING`(ASN1_GENERALSTRING **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_GENERALSTRING`(ASN1_GENERALSTRING *val_in, unsigned char **der_out);

ASN1_T61STRING *
`d2i_ASN1_T61STRING`(ASN1_T61STRING **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_T61STRING`(ASN1_T61STRING *val_in, unsigned char **der_out);

ASN1_VISIBLESTRING *
`d2i_ASN1_VISIBLESTRING`(ASN1_VISIBLESTRING **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_VISIBLESTRING`(ASN1_VISIBLESTRING *val_in, unsigned char **der_out);

ASN1_PRINTABLESTRING *
`d2i_ASN1_PRINTABLESTRING`(ASN1_PRINTABLESTRING **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_PRINTABLESTRING`(ASN1_PRINTABLESTRING *val_in, unsigned char **der_out);

ASN1_STRING *
`d2i_ASN1_PRINTABLE`(ASN1_STRING **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_PRINTABLE`(ASN1_STRING *val_in, unsigned char **der_out);

ASN1_STRING *
`d2i_DIRECTORYSTRING`(ASN1_STRING **val_out, const unsigned char **der_in, long length);

int
`i2d_DIRECTORYSTRING`(ASN1_STRING *val_in, unsigned char **der_out);

ASN1_STRING *
`d2i_DISPLAYTEXT`(ASN1_STRING **val_out, const unsigned char **der_in, long length);

int
`i2d_DISPLAYTEXT`(ASN1_STRING *val_in, unsigned char **der_out);

ASN1_GENERALIZEDTIME *
`d2i_ASN1_GENERALIZEDTIME`(ASN1_GENERALIZEDTIME **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_GENERALIZEDTIME`(ASN1_GENERALIZEDTIME *val_in, unsigned char **der_out);

ASN1_UTCTIME *
`d2i_ASN1_UTCTIME`(ASN1_UTCTIME **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_UTCTIME`(ASN1_UTCTIME *val_in, unsigned char **der_out);

ASN1_TIME *
`d2i_ASN1_TIME`(ASN1_TIME **val_out, const unsigned char **der_in, long length);

int
`i2d_ASN1_TIME`(ASN1_TIME *val_in, unsigned char **der_out);

# DESCRIPTION

These functions decode and encode various ASN.1 built-in types that can be represented by ASN1_STRING objects. For details about the semantics, examples, caveats, and bugs, see ASN1_item_d2i(3).

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:

OpenSSL type | identifier | ASN.1 type
ASN1_OCTET_STRING | 0x04 | OCTET STRING
ASN1_BIT_STRING | 0x03 | BIT STRING
ASN1_INTEGER | 0x02 | INTEGER
ASN1_ENUMERATED | 0x0a | ENUMERATED
ASN1_UTF8STRING | 0x0c | UTF8String
ASN1_IA5STRING | 0x16 | IA5String
ASN1_UNIVERSALSTRING | 0x1c | UniversalString
ASN1_BMPSTRING | 0x1e | BMPString
ASN1_GENERALSTRING | 0x1b | GeneralString
ASN1_T61STRING | 0x14 | T61String
ASN1_VISIBLESTRING | 0x1a | VisibleString
ASN1_PRINTABLESTRING | 0x13 | PrintableString
ASN1_GENERALIZEDTIME | 0x18 | GeneralizedTime
ASN1_UTCTIME | 0x17 | UTCTime

`d2i_DIRECTORYSTRING`() and `i2d_DIRECTORYSTRING`() decode and encode an ASN.1 DirectoryString structure defined in RFC 5280 section 4.1.2.4 and used for ASN.1 EDIPartyName structures; see 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.

`d2i_ASN1_PRINTABLE`() and `i2d_ASN1_PRINTABLE`() are non-standard variants of `d2i_DIRECTORYSTRING`() and `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 DirectoryString in the relative distinguished names described in X509_NAME_ENTRY_new(3), the library accepts this wider range of choices.

`d2i_DISPLAYTEXT`() and `i2d_DISPLAYTEXT`() decode and encode an ASN.1 DisplayText structure defined in RFC 5280 section 4.2.1.4 and used for ASN.1 UserNotice structures in certificate policies; see 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.

`d2i_ASN1_TIME`() and `i2d_ASN1_TIME`() decode and encode an ASN.1 Time structure defined in RFC 5280 section 4.1 and used for ASN.1 Validity structures in certificates; see X509_VAL_new(3). They are also used for certificate revocation lists; see 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.

The following constants describe the ASN.1 tags that are valid when decoding with the above functions. See ASN1_tag2bit(3) for more details about the `B_ASN1_*` constants.

decoding function | mask constant
`d2i_DIRECTORYSTRING`() | `B_ASN1_DIRECTORYSTRING`
`d2i_ASN1_PRINTABLE`() | `B_ASN1_PRINTABLE`
`d2i_DISPLAYTEXT`() | `B_ASN1_DISPLAYTEXT`
`d2i_ASN1_TIME`() | `B_ASN1_TIME`

`d2i_ASN1_UINTEGER`() is similar to `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.

# RETURN VALUES

The `d2i_*`() decoding functions return an ASN1_STRING object or `NULL` if an error occurs.

The `i2d_*`() encoding functions return the number of bytes successfully encoded or a negative value if an error occurs.

# SEE ALSO

ASN1_item_d2i(3), ASN1_STRING_new(3)

# 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

RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile

# HISTORY

`d2i_ASN1_OCTET_STRING`(), `i2d_ASN1_OCTET_STRING`(), `d2i_ASN1_BIT_STRING`(), `i2d_ASN1_BIT_STRING`(), `d2i_ASN1_INTEGER`(), `i2d_ASN1_INTEGER`(), `d2i_ASN1_IA5STRING`(), `i2d_ASN1_IA5STRING`(), `d2i_ASN1_T61STRING`(), `i2d_ASN1_T61STRING`(), `d2i_ASN1_PRINTABLESTRING`(), `i2d_ASN1_PRINTABLESTRING`(), `d2i_ASN1_PRINTABLE`(), `i2d_ASN1_PRINTABLE`(), `d2i_ASN1_UTCTIME`(), and `i2d_ASN1_UTCTIME`() first appeared in SSLeay 0.5.1 and have been available since OpenBSD 2.4.

`d2i_ASN1_BMPSTRING`() and `i2d_ASN1_BMPSTRING`() first appeared in SSLeay 0.9.1. `d2i_ASN1_ENUMERATED`(), `i2d_ASN1_ENUMERATED`(), `d2i_ASN1_GENERALIZEDTIME`(), `i2d_ASN1_GENERALIZEDTIME`(), `d2i_ASN1_TIME`(), and `i2d_ASN1_TIME`() first appeared in OpenSSL 0.9.2b. `d2i_ASN1_UINTEGER`(), `d2i_ASN1_UTF8STRING`(), `i2d_ASN1_UTF8STRING`(), `d2i_ASN1_VISIBLESTRING`(), `i2d_ASN1_VISIBLESTRING`(), `d2i_DIRECTORYSTRING`(), `i2d_DIRECTORYSTRING`(), `d2i_DISPLAYTEXT`() and `i2d_DISPLAYTEXT`() first appeared in OpenSSL 0.9.3. These functions have been available since OpenBSD 2.6.

`d2i_ASN1_UNIVERSALSTRING`(), `i2d_ASN1_UNIVERSALSTRING`(), `d2i_ASN1_GENERALSTRING`(), and `i2d_ASN1_GENERALSTRING`() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2.

# CAVEATS

Other implementations may accept or emit invalid DER encodings of GeneralizedTime and UTCTime. Portable applications should use `ASN1_STRING_length`() to double check whether a given GeneralizedTime or UTCTime object is at least 15 or 13 bytes, respectively.

June 8, 2025 | Debian