OpenBSD manual page server

Manual Page Search Parameters

D2I_ASN1_OCTET_STRING(3) Library Functions Manual D2I_ASN1_OCTET_STRING(3)

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_TIMEdecode and encode ASN1_STRING objects

#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);

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:

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

() and () 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.

() and () 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.

() and () 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.

() and () 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_ASN1_PRINTABLE()
d2i_DISPLAYTEXT()
d2i_ASN1_TIME()

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

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.

ASN1_item_d2i(3), ASN1_STRING_new(3)

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

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.

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.

February 13, 2024 OpenBSD-current