From ed53a826a556d20e0c26bb40367c5ab85dce26f5 Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 15 Nov 2021 13:39:40 +0000 Subject: [PATCH] document ASN1_PRINTABLE_type(3) and ASN1_UNIVERSALSTRING_to_string(3) --- lib/libcrypto/man/ASN1_PRINTABLE_type.3 | 92 +++++++++++++++++++ lib/libcrypto/man/ASN1_STRING_length.3 | 8 +- lib/libcrypto/man/ASN1_STRING_new.3 | 4 +- .../man/ASN1_UNIVERSALSTRING_to_string.3 | 64 +++++++++++++ lib/libcrypto/man/ASN1_mbstring_copy.3 | 8 +- lib/libcrypto/man/Makefile | 4 +- 6 files changed, 172 insertions(+), 8 deletions(-) create mode 100644 lib/libcrypto/man/ASN1_PRINTABLE_type.3 create mode 100644 lib/libcrypto/man/ASN1_UNIVERSALSTRING_to_string.3 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 +.\" +.\" 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 @@ -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 +.\" +.\" 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 .\" @@ -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 @@ -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 \ -- 2.20.1