369 lines
9.9 KiB
Groff
369 lines
9.9 KiB
Groff
.\" $OpenBSD: ASN1_mbstring_copy.3,v 1.6 2022/02/21 00:22:03 jsg Exp $
|
|
.\"
|
|
.\" Copyright (c) 2021 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 21 2022 $
|
|
.Dt ASN1_MBSTRING_COPY 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ASN1_mbstring_copy ,
|
|
.Nm ASN1_mbstring_ncopy ,
|
|
.Nm ASN1_STRING_set_by_NID ,
|
|
.Nm ASN1_STRING_set_default_mask ,
|
|
.Nm ASN1_STRING_set_default_mask_asc ,
|
|
.Nm ASN1_STRING_get_default_mask ,
|
|
.Nm ASN1_tag2bit
|
|
.Nd copy a multibyte string into an ASN.1 string object
|
|
.Sh SYNOPSIS
|
|
.In openssl/asn1.h
|
|
.Ft int
|
|
.Fo ASN1_mbstring_copy
|
|
.Fa "ASN1_STRING **out"
|
|
.Fa "const unsigned char *in"
|
|
.Fa "int inbytes"
|
|
.Fa "int inform"
|
|
.Fa "unsigned long mask"
|
|
.Fc
|
|
.Ft int
|
|
.Fo ASN1_mbstring_ncopy
|
|
.Fa "ASN1_STRING **out"
|
|
.Fa "const unsigned char *in"
|
|
.Fa "int inbytes"
|
|
.Fa "int inform"
|
|
.Fa "unsigned long mask"
|
|
.Fa "long minchars"
|
|
.Fa "long maxchars"
|
|
.Fc
|
|
.Ft ASN1_STRING *
|
|
.Fo ASN1_STRING_set_by_NID
|
|
.Fa "ASN1_STRING **out"
|
|
.Fa "const unsigned char *in"
|
|
.Fa "int inbytes"
|
|
.Fa "int inform"
|
|
.Fa "int nid"
|
|
.Fc
|
|
.Ft void
|
|
.Fo ASN1_STRING_set_default_mask
|
|
.Fa "unsigned long mask"
|
|
.Fc
|
|
.Ft int
|
|
.Fo ASN1_STRING_set_default_mask_asc
|
|
.Fa "const char *maskname"
|
|
.Fc
|
|
.Ft unsigned long
|
|
.Fn ASN1_STRING_get_default_mask void
|
|
.Ft unsigned long
|
|
.Fn ASN1_tag2bit "int tag"
|
|
.Sh DESCRIPTION
|
|
.Fn ASN1_mbstring_copy
|
|
interprets
|
|
.Fa inbytes
|
|
bytes starting at
|
|
.Fa in
|
|
as a multibyte string and copies it to
|
|
.Pf * Fa out ,
|
|
optionally changing the encoding.
|
|
If the
|
|
.Fa inbytes
|
|
argument is negative, the
|
|
.Xr strlen 3
|
|
of
|
|
.Fa in
|
|
is used instead.
|
|
.Pp
|
|
The
|
|
.Fa inform
|
|
argument specifies the character encoding of
|
|
.Fa in :
|
|
.Bl -column MBSTRING_UNIV encoding
|
|
.It Ar inform Ta encoding
|
|
.It Dv MBSTRING_ASC Ta ISO-Latin-1
|
|
.It Dv MBSTRING_BMP Ta UTF-16
|
|
.It Dv MBSTRING_UNIV Ta UTF-32
|
|
.It Dv MBSTRING_UTF8 Ta UTF-8
|
|
.El
|
|
.Pp
|
|
The bit
|
|
.Fa mask
|
|
specifies a set of ASN.1 string types
|
|
that the user is willing to accept:
|
|
.Bl -column B_ASN1_UNIVERSALSTRING ASN1_UNIVERSALSTRING default
|
|
.It bit in Fa mask Ta acceptable output type Ta default
|
|
.It Dv B_ASN1_PRINTABLESTRING Ta Vt ASN1_PRINTABLESTRING Ta yes
|
|
.It Dv B_ASN1_IA5STRING Ta Vt ASN1_IA5STRING Ta no
|
|
.It Dv B_ASN1_T61STRING Ta Vt ASN1_T61STRING Ta yes
|
|
.It Dv B_ASN1_BMPSTRING Ta Vt ASN1_BMPSTRING Ta yes
|
|
.It Dv B_ASN1_UNIVERSALSTRING Ta Vt ASN1_UNIVERSALSTRING Ta no
|
|
.It any other bit Ta Vt ASN1_UTF8STRING Ta yes
|
|
.El
|
|
.Pp
|
|
The first type from the above table that is included in the
|
|
.Fa mask
|
|
argument and that can represent
|
|
.Fa in
|
|
is used as the output type.
|
|
The
|
|
.Dq default
|
|
column indicates whether the type is considered acceptable if the
|
|
.Fa mask
|
|
argument has the special value 0.
|
|
.Pp
|
|
The following bit mask constants
|
|
each include several of the bits listed above:
|
|
.Bl -column B_ASN1_DIRECTORYSTRING_ MMM MMM MMM MMM MMM MMMM
|
|
.It mask constant Ta PRI Ta IA5 Ta T61 Ta BMP Ta UNI Ta UTF8
|
|
.It Dv B_ASN1_DIRECTORYSTRING Ta yes Ta no Ta yes Ta yes Ta yes Ta yes
|
|
.It Dv DIRSTRING_TYPE Ta yes Ta no Ta yes Ta yes Ta no Ta yes
|
|
.It Dv PKCS9STRING_TYPE Ta yes Ta yes Ta yes Ta yes Ta no Ta yes
|
|
.El
|
|
.Pp
|
|
If
|
|
.Fa out
|
|
is
|
|
.Dv NULL ,
|
|
.Fa inform ,
|
|
.Fa inbytes ,
|
|
and
|
|
.Fa in
|
|
are validated and the output type is determined and returned,
|
|
but nothing is copied.
|
|
.Pp
|
|
Otherwise, if
|
|
.Pf * Fa out
|
|
is
|
|
.Dv NULL ,
|
|
a new output object of the output type is allocated
|
|
and a pointer to it is stored in
|
|
.Pf * Fa out .
|
|
.Pp
|
|
Otherwise,
|
|
.Pf ** Fa out
|
|
is used as the output object.
|
|
Any data already stored in it is freed
|
|
and its type is changed to the output type.
|
|
.Pp
|
|
Finally,
|
|
.Fa in
|
|
is copied to the output object, changing the character encoding if
|
|
.Fa inform
|
|
does not match the encoding used by the output type.
|
|
.Pp
|
|
.Fn ASN1_mbstring_ncopy
|
|
is similar except that the number of characters in
|
|
.Fa in
|
|
is restricted to the range from
|
|
.Fa minchars
|
|
to
|
|
.Fa maxchars ,
|
|
inclusive.
|
|
If
|
|
.Fa maxchars
|
|
is 0, no upper limit is enforced on the number of characters.
|
|
.Pp
|
|
.Fn ASN1_STRING_set_by_NID
|
|
is similar with the following differences:
|
|
.Bl -bullet -width 1n
|
|
.It
|
|
If
|
|
.Fa out
|
|
is
|
|
.Dv NULL ,
|
|
a new output object is allocated and returned
|
|
instead of skipping the copying.
|
|
.It
|
|
If
|
|
.Fa nid
|
|
has a global string table entry that can be retrieved with
|
|
.Xr ASN1_STRING_TABLE_get 3 ,
|
|
.Fa mask ,
|
|
.Fa minchars ,
|
|
and
|
|
.Fa maxchars
|
|
are taken from that string table entry.
|
|
For some values of
|
|
.Fa nid ,
|
|
an additional global mask is AND'ed into the mask before using it.
|
|
The default value of the global mask is
|
|
.Dv B_ASN1_UTF8STRING .
|
|
.It
|
|
If
|
|
.Fa nid
|
|
has no global string table entry,
|
|
.Dv B_ASN1_PRINTABLESTRING | B_ASN1_T61STRING |
|
|
.Dv B_ASN1_BMPSTRING | B_ASN1_UTF8STRING
|
|
is used instead of the mask taken from the table,
|
|
and the global mask is also AND'ed into it.
|
|
.It
|
|
Even though success and failure happen in the same situations,
|
|
the return value is different.
|
|
.Xr ASN1_STRING_type 3
|
|
can be used to determine the type of the return value.
|
|
.El
|
|
.Pp
|
|
.Fn ASN1_STRING_set_default_mask
|
|
sets the global mask used by
|
|
.Fn ASN1_STRING_set_by_NID
|
|
to the
|
|
.Fa mask
|
|
argument.
|
|
.Pp
|
|
.Fn ASN1_STRING_set_default_mask_asc
|
|
sets the global mask as follows:
|
|
.Bl -column utf8only
|
|
.It Ar maskname Ta Ar mask
|
|
.It Qo default Qc Ta anything
|
|
.It Qo nombstr Qc Ta anything except Dv B_ASN1_BMPSTRING | B_ASN1_UTF8STRING
|
|
.It Qo pkix Qc Ta anything except Dv B_ASN1_T61STRING
|
|
.It Qo utf8only Qc Ta Dv B_ASN1_UTF8STRING
|
|
.El
|
|
.Pp
|
|
If the
|
|
.Fa maskname
|
|
argument starts with the substring
|
|
.Qq MASK:\& ,
|
|
the rest of it is interpreted as an
|
|
.Vt unsigned long
|
|
value using
|
|
.Xr strtoul 3 .
|
|
.Pp
|
|
.Fn ASN1_tag2bit
|
|
translates ASN.1 data types to type bits as follows:
|
|
.Bl -column V_ASN1_OBJECT_DESCRIPTOR B_ASN1_UNIVERSALSTRING
|
|
.It Fa tag Ta return value
|
|
.It Dv V_ASN1_BIT_STRING Ta Dv B_ASN1_BIT_STRING
|
|
.It Dv V_ASN1_BMPSTRING Ta Dv B_ASN1_BMPSTRING
|
|
.It Dv V_ASN1_BOOLEAN Ta 0
|
|
.It Dv V_ASN1_ENUMERATED Ta Dv B_ASN1_UNKNOWN
|
|
.It Dv V_ASN1_EOC Ta 0
|
|
.It Dv V_ASN1_EXTERNAL Ta Dv B_ASN1_UNKNOWN
|
|
.It Dv V_ASN1_GENERALIZEDTIME Ta Dv B_ASN1_GENERALIZEDTIME
|
|
.It Dv V_ASN1_GENERALSTRING Ta Dv B_ASN1_GENERALSTRING
|
|
.It Dv V_ASN1_GRAPHICSTRING Ta Dv B_ASN1_GRAPHICSTRING
|
|
.It Dv V_ASN1_IA5STRING Ta Dv B_ASN1_IA5STRING
|
|
.It Dv V_ASN1_INTEGER Ta 0
|
|
.It Dv V_ASN1_ISO64STRING Ta Dv B_ASN1_ISO64STRING
|
|
.It Dv V_ASN1_NULL Ta 0
|
|
.It Dv V_ASN1_NUMERICSTRING Ta Dv B_ASN1_NUMERICSTRING
|
|
.It Dv V_ASN1_OBJECT Ta 0
|
|
.It Dv V_ASN1_OBJECT_DESCRIPTOR Ta Dv B_ASN1_UNKNOWN
|
|
.It Dv V_ASN1_OCTET_STRING Ta Dv B_ASN1_OCTET_STRING
|
|
.It Dv V_ASN1_PRINTABLESTRING Ta Dv B_ASN1_PRINTABLESTRING
|
|
.It Dv V_ASN1_REAL Ta Dv B_ASN1_UNKNOWN
|
|
.It Dv V_ASN1_SEQUENCE Ta Dv B_ASN1_SEQUENCE
|
|
.It Dv V_ASN1_SET Ta 0
|
|
.It Dv V_ASN1_T61STRING Ta Dv B_ASN1_T61STRING
|
|
.It Dv V_ASN1_TELETEXSTRING Ta Dv B_ASN1_TELETEXSTRING
|
|
.It Dv V_ASN1_UNDEF Ta 0
|
|
.It Dv V_ASN1_UNIVERSALSTRING Ta Dv B_ASN1_UNIVERSALSTRING
|
|
.It Dv V_ASN1_UTCTIME Ta Dv B_ASN1_UTCTIME
|
|
.It Dv V_ASN1_UTF8STRING Ta Dv B_ASN1_UTF8STRING
|
|
.It Dv V_ASN1_VIDEOTEXSTRING Ta Dv B_ASN1_VIDEOTEXSTRING
|
|
.It Dv V_ASN1_VISIBLESTRING Ta Dv B_ASN1_VISIBLESTRING
|
|
.It 11, 13, 14, 15, 29 Ta Dv B_ASN1_UNKNOWN
|
|
.It Dv other Po < 0, > 30 Pc Ta Dv 0
|
|
.El
|
|
.Pp
|
|
In typical usage, the calling code calculates the bitwise AND
|
|
of the return value and a mask describing data types
|
|
that the calling code is willing to use.
|
|
If the result of the AND operation is non-zero, the data type is
|
|
adequate; otherwise, the calling code may need to raise an error.
|
|
.Sh RETURN VALUES
|
|
.Fn ASN1_mbstring_copy
|
|
and
|
|
.Fn ASN1_mbstring_ncopy
|
|
return the
|
|
.Dv V_ASN1_*
|
|
constant representing the output type or \-1 if
|
|
.Fa inform
|
|
is invalid, if
|
|
.Fa inbytes
|
|
or
|
|
.Fa in
|
|
is invalid for the
|
|
.Fa inform
|
|
encoding, if
|
|
.Fa in
|
|
contains an UTF-16 surrogate,
|
|
which is unsupported even for input using the UTF-16 encoding,
|
|
or if memory allocation fails.
|
|
.Pp
|
|
.Fn ASN1_mbstring_ncopy
|
|
also returns \-1 if
|
|
.Fa in
|
|
contains fewer than
|
|
.Fa minchars
|
|
or more than
|
|
.Fa maxchars
|
|
characters.
|
|
.Pp
|
|
.Fn ASN1_STRING_set_by_NID
|
|
returns the new or changed ASN.1 string object or
|
|
.Dv NULL
|
|
on failure.
|
|
.Pp
|
|
.Fn ASN1_STRING_set_default_mask_asc
|
|
returns 1 if successful or 0 if
|
|
.Qq MASK:\&
|
|
is not followed by a number, if the number is followed by a non-numeric
|
|
character, or if the
|
|
.Fa maskname
|
|
is invalid.
|
|
.Pp
|
|
.Fn ASN1_STRING_get_default_mask
|
|
returns the global mask.
|
|
.Pp
|
|
.Fn ASN1_tag2bit
|
|
returns a
|
|
.Dv B_ASN1_*
|
|
constant or 0.
|
|
.Sh SEE ALSO
|
|
.Xr ASN1_PRINTABLE_type 3 ,
|
|
.Xr ASN1_STRING_new 3 ,
|
|
.Xr ASN1_STRING_set 3 ,
|
|
.Xr ASN1_STRING_TABLE_get 3 ,
|
|
.Xr ASN1_UNIVERSALSTRING_to_string 3
|
|
.Sh HISTORY
|
|
.Fn ASN1_mbstring_copy ,
|
|
.Fn ASN1_mbstring_ncopy ,
|
|
.Fn ASN1_STRING_set_by_NID ,
|
|
.Fn ASN1_STRING_set_default_mask ,
|
|
.Fn ASN1_STRING_set_default_mask_asc ,
|
|
and
|
|
.Fn ASN1_STRING_get_default_mask
|
|
first appeared in OpenSSL 0.9.5 and have been available since
|
|
.Ox 2.7 .
|
|
.Pp
|
|
.Fn ASN1_tag2bit
|
|
first appeared in OpenSSL 0.9.7 and has been available since
|
|
.Ox 3.2 .
|
|
.Sh BUGS
|
|
If integer overflow occurs in
|
|
.Fn ASN1_STRING_set_default_mask_asc
|
|
while parsing a number following
|
|
.Qq MASK:\& ,
|
|
the function succeeds, essentially behaving in the same way as for
|
|
.Qq default .
|
|
.Pp
|
|
Passing
|
|
.Qq default
|
|
to
|
|
.Fn ASN1_STRING_set_default_mask_asc
|
|
does
|
|
.Em not
|
|
restore the default mask.
|
|
Instead, passing
|
|
.Qq utf8only
|
|
does that.
|