document ASN1_PRINTABLE_type(3) and ASN1_UNIVERSALSTRING_to_string(3)

6 files changed, 172 insertions, 8 deletions

diff --git a/lib/libcrypto/man/ASN1_PRINTABLE_type.3 b/lib/libcrypto/man/ASN1_PRINTABLE_type.3
new file mode 100644
index 00000000000..391dd32e664
--- /dev/null
+++ b/lib/libcrypto/man/ASN1_PRINTABLE_type.3
@@ -0,0 +1,92 @@
+.\" $OpenBSD: ASN1_PRINTABLE_type.3,v 1.1 2021/11/15 13:39:40 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: November 15 2021 $
+.Dt ASN1_PRINTABLE_TYPE 3
+.Os
+.Sh NAME
+.Nm ASN1_PRINTABLE_type
+.Nd classify a single-byte character string
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft int
+.Fo ASN1_PRINTABLE_type
+.Fa "const unsigned char *string"
+.Fa "int len"
+.Fc
+.Sh DESCRIPTION
+.Fn ASN1_PRINTABLE_type
+assumes that the given
+.Fa string
+consists of single-byte characters and classifies it
+according to which kinds characters occur.
+If
+.Fa len
+is greater than 0, at most
+.Fa len
+characters are inspected.
+Otherwise, the
+.Fa string
+needs to be NUL-terminated.
+.Sh RETURN VALUES
+If the given
+.Fa string
+contains a character outside the
+.Xr ascii 7
+range,
+.Fn ASN1_PRINTABLE_type
+returns
+.Dv V_ASN1_T61STRING .
+.Pp
+Otherwise, if it contains a character that is neither a letter
+nor a digit nor the space character
+.Po
+.Ql "\ " ,
+ASCII 0x20
+.Pc
+nor the apostrophe quote
+.Po
+.Ql \(aq ,
+ASCII 0x27
+.Pc
+nor contained in the set
+.Qq ()+,\-./:=?\& ,
+it returns
+.Dv V_ASN1_IA5STRING .
+.Pp
+Otherwise, including if
+.Fa string
+is a
+.Dv NULL
+pointer or points to an empty string, it returns
+.Dv V_ASN1_PRINTABLESTRING .
+.Sh SEE ALSO
+.Xr ASN1_mbstring_copy 3 ,
+.Xr ASN1_STRING_new 3 ,
+.Xr ASN1_STRING_to_UTF8 3 ,
+.Xr isascii 3 ,
+.Xr ascii 7
+.Sh HISTORY
+.Fn ASN1_PRINTABLE_type
+first appeared in SSLeay 0.4.5d, has been part of the public API
+since SSLeay 0.5.1, and has been available since
+.Ox 2.4 .
+.Sh CAVEATS
+The ASN.1 notion of what constitutes a
+.Vt PrintableString
+is more restrictive than what the C library function
+.Xr isprint 3
+considers printable.
diff --git a/lib/libcrypto/man/ASN1_STRING_length.3 b/lib/libcrypto/man/ASN1_STRING_length.3
index e24dd183730..5a113ecb223 100644
--- a/lib/libcrypto/man/ASN1_STRING_length.3
+++ b/lib/libcrypto/man/ASN1_STRING_length.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_STRING_length.3,v 1.24 2021/11/14 11:22:36 schwarze Exp $
+.\" $OpenBSD: ASN1_STRING_length.3,v 1.25 2021/11/15 13:39:40 schwarze Exp $
 .\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
 .\" 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: November 14 2021 $
+.Dd $Mdocdate: November 15 2021 $
 .Dt ASN1_STRING_LENGTH 3
 .Os
 .Sh NAME
@@ -381,7 +381,9 @@ the reason can be determined with
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
 .Xr ASN1_mbstring_copy 3 ,
-.Xr ASN1_STRING_new 3
+.Xr ASN1_PRINTABLE_type 3 ,
+.Xr ASN1_STRING_new 3 ,
+.Xr ASN1_UNIVERSALSTRING_to_string 3
 .Sh HISTORY
 .Fn ASN1_STRING_cmp ,
 .Fn ASN1_STRING_dup ,
diff --git a/lib/libcrypto/man/ASN1_STRING_new.3 b/lib/libcrypto/man/ASN1_STRING_new.3
index a2cd27ecb85..23679cdb3cc 100644
--- a/lib/libcrypto/man/ASN1_STRING_new.3
+++ b/lib/libcrypto/man/ASN1_STRING_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ASN1_STRING_new.3,v 1.20 2021/11/15 11:51:09 schwarze Exp $
+.\"	$OpenBSD: ASN1_STRING_new.3,v 1.21 2021/11/15 13:39:40 schwarze Exp $
 .\"	OpenSSL 99d63d46 Tue Mar 24 07:52:24 2015 -0400
 .\"
 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -206,11 +206,13 @@ is returned and an error code can be retrieved with
 .Xr ASN1_INTEGER_get 3 ,
 .Xr ASN1_item_pack 3 ,
 .Xr ASN1_mbstring_copy 3 ,
+.Xr ASN1_PRINTABLE_type 3 ,
 .Xr ASN1_STRING_length 3 ,
 .Xr ASN1_STRING_print_ex 3 ,
 .Xr ASN1_time_parse 3 ,
 .Xr ASN1_TIME_set 3 ,
 .Xr ASN1_TYPE_get 3 ,
+.Xr ASN1_UNIVERSALSTRING_to_string 3 ,
 .Xr d2i_ASN1_OBJECT 3 ,
 .Xr d2i_ASN1_OCTET_STRING 3 ,
 .Xr i2a_ASN1_STRING 3 ,
diff --git a/lib/libcrypto/man/ASN1_UNIVERSALSTRING_to_string.3 b/lib/libcrypto/man/ASN1_UNIVERSALSTRING_to_string.3
new file mode 100644
index 00000000000..2af675295b3
--- /dev/null
+++ b/lib/libcrypto/man/ASN1_UNIVERSALSTRING_to_string.3
@@ -0,0 +1,64 @@
+.\" $OpenBSD: ASN1_UNIVERSALSTRING_to_string.3,v 1.1 2021/11/15 13:39:40 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: November 15 2021 $
+.Dt ASN1_UNIVERSALSTRING_TO_STRING 3
+.Os
+.Sh NAME
+.Nm ASN1_UNIVERSALSTRING_to_string
+.Nd recode UTF-32 to ISO Latin-1
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft int
+.Fo ASN1_UNIVERSALSTRING_to_string
+.Fa "ASN1_UNIVERSALSTRING *string"
+.Fc
+.Sh DESCRIPTION
+.Fn ASN1_UNIVERSALSTRING_to_string
+assumes that the given
+.Fa string
+is encoded in UTF-32, recodes it in place to ISO Latin-1,
+and changes the type according to
+.Xr ASN1_PRINTABLE_type 3 .
+.Pp
+.Fn ASN1_UNIVERSALSTRING_to_string
+fails and leaves the
+.Fa string
+unchanged if its
+.Xr ASN1_STRING_type 3
+is not
+.Dv V_ASN1_UNIVERSALSTRING ,
+if its
+.Xr ASN1_STRING_length 3
+is not a multiple of four bytes,
+or if any of its characters cannot be represented in ISO Latin-1.
+.Pp
+In case of success, the
+.Xr ASN1_STRING_length 3
+of the
+.Fa string
+is reduced by a factor of four.
+.Sh RETURN VALUES
+.Fn ASN1_UNIVERSALSTRING_to_string
+returns 1 on success or 0 on failure.
+.Sh SEE ALSO
+.Xr ASN1_mbstring_copy 3 ,
+.Xr ASN1_STRING_new 3 ,
+.Xr ASN1_STRING_to_UTF8 3
+.Sh HISTORY
+.Fn ASN1_UNIVERSALSTRING_to_string
+first appeared in SSLeay 0.8.0 and has been available since
+.Ox 2.4 .
diff --git a/lib/libcrypto/man/ASN1_mbstring_copy.3 b/lib/libcrypto/man/ASN1_mbstring_copy.3
index ce270c8d5ed..b499c3b8b21 100644
--- a/lib/libcrypto/man/ASN1_mbstring_copy.3
+++ b/lib/libcrypto/man/ASN1_mbstring_copy.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_mbstring_copy.3,v 1.2 2021/10/20 15:54:21 schwarze Exp $
+.\" $OpenBSD: ASN1_mbstring_copy.3,v 1.3 2021/11/15 13:39:40 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,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: October 20 2021 $
+.Dd $Mdocdate: November 15 2021 $
 .Dt ASN1_MBSTRING_COPY 3
 .Os
 .Sh NAME
@@ -270,9 +270,11 @@ is invalid.
 .Fn ASN1_STRING_get_default_mask
 returns the global mask.
 .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_STRING_TABLE_get 3 ,
+.Xr ASN1_UNIVERSALSTRING_to_string 3
 .Sh HISTORY
 These functions first appeared in OpenSSL 0.9.5
 and have been available since
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index ab7740054ea..2af6c166578 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.213 2021/11/15 11:51:09 schwarze Exp $
+# $OpenBSD: Makefile,v 1.214 2021/11/15 13:39:40 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -7,12 +7,14 @@ MAN=	\
 	AES_encrypt.3 \
 	ASN1_INTEGER_get.3 \
 	ASN1_OBJECT_new.3 \
+	ASN1_PRINTABLE_type.3 \
 	ASN1_STRING_TABLE_add.3 \
 	ASN1_STRING_length.3 \
 	ASN1_STRING_new.3 \
 	ASN1_STRING_print_ex.3 \
 	ASN1_TIME_set.3 \
 	ASN1_TYPE_get.3 \
+	ASN1_UNIVERSALSTRING_to_string.3 \
 	ASN1_generate_nconf.3 \
 	ASN1_get_object.3 \
 	ASN1_item_d2i.3 \