462 lines
12 KiB
Groff
462 lines
12 KiB
Groff
.\" $OpenBSD: d2i_ASN1_OCTET_STRING.3,v 1.20 2024/02/13 12:38:43 job 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: February 13 2024 $
|
|
.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.
|
|
.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 .
|
|
.Sh CAVEATS
|
|
Other implementations may accept or emit invalid DER encodings of
|
|
GeneralizedTime and UTCTime.
|
|
Portable applications should use
|
|
.Fn ASN1_STRING_length
|
|
to double check whether a given GeneralizedTime or UTCTime object is at least
|
|
15 or 13 bytes, respectively.
|