.\"	$OpenBSD: d2i_ASN1_OCTET_STRING.3,v 1.5 2017/08/01 14:57:03 schwarze Exp $
.\"
.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" 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: August 1 2017 $
.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 octet,
one or more length octets,
and one or more content octets.
The identifier octets 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
octets (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
.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