path: root/lib/libcrypto/man/d2i_ASN1_OCTET_STRING.3

.\"	$OpenBSD: d2i_ASN1_OCTET_STRING.3,v 1.18 2022/09/12 14:33:47 tb 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: September 12 2022 $
.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 byte, one or more length bytes,
and one or more content bytes.
The identifier bytes 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
bytes (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
The following constants describe the ASN.1 tags that are valid
when decoding with the above functions.
See
.Xr ASN1_tag2bit 3
for more details about the
.Dv B_ASN1_*
constants.
.Bl -column d2i_DIRECTORYSTRING() B_ASN1_DIRECTORYSTRING -offset indent
.It decoding function      Ta mask constant
.It Fn d2i_DIRECTORYSTRING Ta Dv B_ASN1_DIRECTORYSTRING
.It Fn d2i_ASN1_PRINTABLE  Ta Dv B_ASN1_PRINTABLE
.It Fn d2i_DISPLAYTEXT     Ta Dv B_ASN1_DISPLAYTEXT
.It Fn d2i_ASN1_TIME       Ta Dv B_ASN1_TIME
.El
.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.
.Pp
.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
.Sh HISTORY
.Fn d2i_ASN1_OCTET_STRING ,
.Fn i2d_ASN1_OCTET_STRING ,
.Fn d2i_ASN1_BIT_STRING ,
.Fn i2d_ASN1_BIT_STRING ,
.Fn d2i_ASN1_INTEGER ,
.Fn i2d_ASN1_INTEGER ,
.Fn d2i_ASN1_IA5STRING ,
.Fn i2d_ASN1_IA5STRING ,
.Fn d2i_ASN1_T61STRING ,
.Fn i2d_ASN1_T61STRING ,
.Fn d2i_ASN1_PRINTABLESTRING ,
.Fn i2d_ASN1_PRINTABLESTRING ,
.Fn d2i_ASN1_PRINTABLE ,
.Fn i2d_ASN1_PRINTABLE ,
.Fn d2i_ASN1_UTCTIME ,
and
.Fn i2d_ASN1_UTCTIME
first appeared in SSLeay 0.5.1 and have been available since
.Ox 2.4 .
.Pp
.Fn d2i_ASN1_BMPSTRING
and
.Fn i2d_ASN1_BMPSTRING
first appeared in SSLeay 0.9.1.
.Fn d2i_ASN1_ENUMERATED ,
.Fn i2d_ASN1_ENUMERATED ,
.Fn d2i_ASN1_GENERALIZEDTIME ,
.Fn i2d_ASN1_GENERALIZEDTIME ,
.Fn d2i_ASN1_TIME ,
and
.Fn i2d_ASN1_TIME
first appeared in OpenSSL 0.9.2b.
.Fn d2i_ASN1_UINTEGER ,
.Fn d2i_ASN1_UTF8STRING ,
.Fn i2d_ASN1_UTF8STRING ,
.Fn d2i_ASN1_VISIBLESTRING ,
.Fn i2d_ASN1_VISIBLESTRING ,
.Fn d2i_DIRECTORYSTRING ,
.Fn i2d_DIRECTORYSTRING ,
.Fn d2i_DISPLAYTEXT
and
.Fn i2d_DISPLAYTEXT
first appeared in OpenSSL 0.9.3.
These functions have been available since
.Ox 2.6 .
.Pp
.Fn d2i_ASN1_UNIVERSALSTRING ,
.Fn i2d_ASN1_UNIVERSALSTRING ,
.Fn d2i_ASN1_GENERALSTRING ,
and
.Fn i2d_ASN1_GENERALSTRING
first appeared in OpenSSL 0.9.7 and have been available since
.Ox 3.2 .