new manual page ASN1_mbstring_copy(3)

also documenting ASN1_mbstring_ncopy(3)

4 files changed, 182 insertions, 5 deletions

diff --git a/src/lib/libcrypto/man/ASN1_STRING_length.3 b/src/lib/libcrypto/man/ASN1_STRING_length.3
index b87cf9987c..76679e27e9 100644
--- a/src/lib/libcrypto/man/ASN1_STRING_length.3
+++ b/src/lib/libcrypto/man/ASN1_STRING_length.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_STRING_length.3,v 1.20 2019/08/26 07:59:02 schwarze Exp $
+.\" $OpenBSD: ASN1_STRING_length.3,v 1.21 2021/10/20 13:14:00 schwarze Exp $
 .\" full merge up to: OpenSSL 4a56d2a3 Feb 25 16:49:27 2018 +0300
 .\"
 .\" This file is a derived work.
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 26 2019 $
+.Dd $Mdocdate: October 20 2021 $
 .Dt ASN1_STRING_LENGTH 3
 .Os
 .Sh NAME
@@ -326,6 +326,7 @@ and
 the reason can be determined with
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
+.Xr ASN1_mbstring_copy 3 ,
 .Xr ASN1_STRING_new 3
 .Sh HISTORY
 .Fn ASN1_STRING_cmp ,
diff --git a/src/lib/libcrypto/man/ASN1_STRING_new.3 b/src/lib/libcrypto/man/ASN1_STRING_new.3
index 46325f3968..ce2e9fdc68 100644
--- a/src/lib/libcrypto/man/ASN1_STRING_new.3
+++ b/src/lib/libcrypto/man/ASN1_STRING_new.3
@@ -1,4 +1,4 @@
-.\"     $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>
@@ -15,7 +15,7 @@
 .\" 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
@@ -204,6 +204,7 @@ is returned and an error code can be retrieved with
 .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 ,
diff --git a/src/lib/libcrypto/man/ASN1_mbstring_copy.3 b/src/lib/libcrypto/man/ASN1_mbstring_copy.3
new file mode 100644
index 0000000000..0ce110d6ed
--- /dev/null
+++ b/src/lib/libcrypto/man/ASN1_mbstring_copy.3
@@ -0,0 +1,174 @@
+.\" $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 .
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 97c6b3e9a4..0f6b84a1b6 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.194 2021/10/20 05:06:36 schwarze Exp $
+# $OpenBSD: Makefile,v 1.195 2021/10/20 13:14:00 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -17,6 +17,7 @@ MAN=	\
         ASN1_get_object.3 \
         ASN1_item_d2i.3 \
         ASN1_item_new.3 \
+        ASN1_mbstring_copy.3 \
         ASN1_parse_dump.3 \
         ASN1_put_object.3 \
         ASN1_time_parse.3 \