OpenBSD manual page server

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

#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:

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.

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.