1 files changed, 174 insertions, 0 deletions
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/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 @@
	1	.\" $OpenBSD: ASN1_mbstring_copy.3,v 1.1 2021/10/20 13:14:00 schwarze Exp $
	2	.\"
	3	.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
	4	.\"
	5	.\" Permission to use, copy, modify, and distribute this software for any
	6	.\" purpose with or without fee is hereby granted, provided that the above
	7	.\" copyright notice and this permission notice appear in all copies.
	8	.\"
	9	.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
	10	.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
	11	.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
	12	.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
	13	.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
	14	.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
	15	.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
	16	.\"
	17	.Dd $Mdocdate: October 20 2021 $
	18	.Dt ASN1_MBSTRING_COPY 3
	19	.Os
	20	.Sh NAME
	21	.Nm ASN1_mbstring_copy ,
	22	.Nm ASN1_mbstring_ncopy
	23	.Nd copy a mutibyte string into an ASN.1 string object
	24	.Sh SYNOPSIS
	25	.In openssl/asn1.h
	26	.Ft int
	27	.Fo ASN1_mbstring_copy
	28	.Fa "ASN1_STRING **out"
	29	.Fa "const unsigned char *in"
	30	.Fa "int inbytes"
	31	.Fa "int inform"
	32	.Fa "unsigned long mask"
	33	.Fc
	34	.Ft int
	35	.Fo ASN1_mbstring_ncopy
	36	.Fa "ASN1_STRING **out"
	37	.Fa "const unsigned char *in"
	38	.Fa "int inbytes"
	39	.Fa "int inform"
	40	.Fa "unsigned long mask"
	41	.Fa "long minchars"
	42	.Fa "long maxchars"
	43	.Fc
	44	.Sh DESCRIPTION
	45	.Fn ASN1_mbstring_copy
	46	interprets
	47	.Fa inbytes
	48	bytes starting at
	49	.Fa in
	50	as a multibyte string and copies it to
	51	.Pf * Fa out ,
	52	optionally changing the encoding.
	53	If the
	54	.Fa inbytes
	55	argument is negative, the
	56	.Xr strlen 3
	57	of
	58	.Fa in
	59	is used instead.
	60	.Pp
	61	The
	62	.Fa inform
	63	argument specifies the character encoding of
	64	.Fa in :
	65	.Bl -column MBSTRING_UNIV encoding
	66	.It Ar inform Ta encoding
	67	.It Dv MBSTRING_ASC Ta ISO-Latin-1
	68	.It Dv MBSTRING_BMP Ta UTF-16
	69	.It Dv MBSTRING_UNIV Ta UTF-32
	70	.It Dv MBSTRING_UTF8 Ta UTF-8
	71	.El
	72	.Pp
	73	The bit
	74	.Fa mask
	75	specifies a set of ASN.1 string types
	76	that the user is willing to accept:
	77	.Bl -column B_ASN1_UNIVERSALSTRING ASN1_UNIVERSALSTRING default
	78	.It bit in Fa mask Ta acceptable output type Ta default
	79	.It Dv B_ASN1_PRINTABLESTRING Ta Vt ASN1_PRINTABLESTRING Ta yes
	80	.It Dv B_ASN1_IA5STRING Ta Vt ASN1_IA5STRING Ta no
	81	.It Dv B_ASN1_T61STRING Ta Vt ASN1_T61STRING Ta yes
	82	.It Dv B_ASN1_BMPSTRING Ta Vt ASN1_BMPSTRING Ta yes
	83	.It Dv B_ASN1_UNIVERSALSTRING Ta Vt ASN1_UNIVERSALSTRING Ta no
	84	.It any other bit Ta Vt ASN1_UTF8STRING Ta yes
	85	.El
	86	.Pp
	87	The first type from the above table that is included in the
	88	.Fa mask
	89	argument and that can represent
	90	.Fa in
	91	is used as the output type.
	92	The
	93	.Dq default
	94	column indicates whether the type is considered acceptable if the
	95	.Fa mask
	96	argument has the special value 0.
	97	.Pp
	98	If
	99	.Fa out
	100	is
	101	.Dv NULL ,
	102	.Fa inform ,
	103	.Fa inbytes ,
	104	and
	105	.Fa in
	106	are validated and the output type is determined and returned,
	107	but nothing is copied.
	108	.Pp
	109	Otherwise, if
	110	.Pf * Fa out
	111	is
	112	.Dv NULL ,
	113	a new output object of the output type is allocated
	114	and a pointer to it is stored in
	115	.Pf * Fa out .
	116	.Pp
	117	Otherwise,
	118	.Pf ** Fa out
	119	is used as the output object.
	120	Any data already stored in it is freed
	121	and its type is changed to the output type.
	122	.Pp
	123	Finally,
	124	.Fa in
	125	is copied to the output object, changing the character encoding if
	126	.Fa inform
	127	does not match the encoding used by the output type.
	128	.Pp
	129	.Fn ASN1_mbstring_ncopy
	130	is similar except that the number of characters in
	131	.Fa in
	132	is restricted to the range from
	133	.Fa minchars
	134	to
	135	.Fa maxchars ,
	136	inclusive.
	137	If
	138	.Fa maxchars
	139	is 0, no upper limit is enforced on the number of characters.
	140	.Sh RETURN VALUES
	141	.Fn ASN1_mbstring_copy
	142	and
	143	.Fn ASN1_mbstring_ncopy
	144	return the
	145	.Dv V_ASN1_*
	146	constant representing the output type or \-1 if
	147	.Fa inform
	148	is invalid, if
	149	.Fa inbytes
	150	or
	151	.Fa in
	152	is invalid for the
	153	.Fa inform
	154	encoding, if
	155	.Fa in
	156	contains an UTF-16 surrogate,
	157	which is unsupported even for input using the UTF-16 encoding,
	158	or if memory allocation fails.
	159	.Pp
	160	.Fn ASN1_mbstring_ncopy
	161	also returns \-1 if
	162	.Fa in
	163	contains fewer than
	164	.Fa minchars
	165	or more than
	166	.Fa maxchars
	167	characters.
	168	.Sh SEE ALSO
	169	.Xr ASN1_STRING_new 3 ,
	170	.Xr ASN1_STRING_set 3
	171	.Sh HISTORY
	172	These functions first appeared in OpenSSL 0.9.5
	173	and have been available since
	174	.Ox 2.7 .