-.\" $OpenBSD: ASN1_STRING_new.3,v 1.17 2019/06/14 13:59:32 schwarze Exp $
+.\" $OpenBSD: ASN1_STRING_new.3,v 1.18 2021/10/20 13:14:00 schwarze Exp $
.\" OpenSSL 99d63d46 Tue Mar 24 07:52:24 2015 -0400
.\"
.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: June 14 2019 $
+.Dd $Mdocdate: October 20 2021 $
.Dt ASN1_STRING_NEW 3
.Os
.Sh NAME
.Xr ERR_get_error 3 .
.Sh SEE ALSO
.Xr ASN1_INTEGER_get 3 ,
+.Xr ASN1_mbstring_copy 3 ,
.Xr ASN1_STRING_length 3 ,
.Xr ASN1_STRING_print_ex 3 ,
.Xr ASN1_time_parse 3 ,
--- /dev/null
+.\" $OpenBSD: ASN1_mbstring_copy.3,v 1.1 2021/10/20 13:14:00 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
+.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
+.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.
+.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.
+.Sh SEE ALSO
+.Xr ASN1_STRING_new 3 ,
+.Xr ASN1_STRING_set 3
+.Sh HISTORY
+These functions first appeared in OpenSSL 0.9.5
+and have been available since
+.Ox 2.7 .
projects / openbsd / commitdiff