From 0143b33fa20c3da5cbf1bb6d1cf27021639e7ea2 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 20 Oct 2021 13:14:00 +0000 Subject: new manual page ASN1_mbstring_copy(3) also documenting ASN1_mbstring_ncopy(3) --- src/lib/libcrypto/man/ASN1_STRING_length.3 | 5 +- src/lib/libcrypto/man/ASN1_STRING_new.3 | 5 +- src/lib/libcrypto/man/ASN1_mbstring_copy.3 | 174 +++++++++++++++++++++++++++++ src/lib/libcrypto/man/Makefile | 3 +- 4 files changed, 182 insertions(+), 5 deletions(-) create mode 100644 src/lib/libcrypto/man/ASN1_mbstring_copy.3 (limited to 'src/lib/libcrypto/man') 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 @@ -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 +.\" +.\" 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 @@ -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 \ -- cgit v1.2.3-55-g6feb