current nightly

Sortix nightly manual

This manual documents Sortix nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.

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:

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.

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.