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

.\" $OpenBSD: ASN1_mbstring_copy.3,v 1.2 2021/10/20 15:54:21 schwarze 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: October 20 2021 $
.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
.Nd copy a mutibyte 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
.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
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 .
.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.
.Sh SEE ALSO
.Xr ASN1_STRING_new 3 ,
.Xr ASN1_STRING_set 3 ,
.Xr ASN1_STRING_TABLE_get 3
.Sh HISTORY
These functions first appeared in OpenSSL 0.9.5
and have been available since
.Ox 2.7 .
.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.