From eb8dd9dca1228af0cd132f515509051ecfabf6f6 Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Mon, 14 Apr 2025 17:32:06 +0000 Subject: This commit was manufactured by cvs2git to create tag 'tb_20250414'. --- src/lib/libcrypto/man/ASN1_mbstring_copy.3 | 369 ----------------------------- 1 file changed, 369 deletions(-) delete mode 100644 src/lib/libcrypto/man/ASN1_mbstring_copy.3 (limited to 'src/lib/libcrypto/man/ASN1_mbstring_copy.3') diff --git a/src/lib/libcrypto/man/ASN1_mbstring_copy.3 b/src/lib/libcrypto/man/ASN1_mbstring_copy.3 deleted file mode 100644 index e0b48aaa62..0000000000 --- a/src/lib/libcrypto/man/ASN1_mbstring_copy.3 +++ /dev/null @@ -1,369 +0,0 @@ -.\" $OpenBSD: ASN1_mbstring_copy.3,v 1.6 2022/02/21 00:22:03 jsg 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: February 21 2022 $ -.Dt ASN1_MBSTRING_COPY 3 -.Os -.Sh NAME -.Nm ASN1_mbstring_copy , -.Nm ASN1_mbstring_ncopy , -.Nm ASN1_STRING_set_by_NID , -.Nm ASN1_STRING_set_default_mask , -.Nm ASN1_STRING_set_default_mask_asc , -.Nm ASN1_STRING_get_default_mask , -.Nm ASN1_tag2bit -.Nd copy a multibyte 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 -.Ft ASN1_STRING * -.Fo ASN1_STRING_set_by_NID -.Fa "ASN1_STRING **out" -.Fa "const unsigned char *in" -.Fa "int inbytes" -.Fa "int inform" -.Fa "int nid" -.Fc -.Ft void -.Fo ASN1_STRING_set_default_mask -.Fa "unsigned long mask" -.Fc -.Ft int -.Fo ASN1_STRING_set_default_mask_asc -.Fa "const char *maskname" -.Fc -.Ft unsigned long -.Fn ASN1_STRING_get_default_mask void -.Ft unsigned long -.Fn ASN1_tag2bit "int tag" -.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 -The following bit mask constants -each include several of the bits listed above: -.Bl -column B_ASN1_DIRECTORYSTRING_ MMM MMM MMM MMM MMM MMMM -.It mask constant Ta PRI Ta IA5 Ta T61 Ta BMP Ta UNI Ta UTF8 -.It Dv B_ASN1_DIRECTORYSTRING Ta yes Ta no Ta yes Ta yes Ta yes Ta yes -.It Dv DIRSTRING_TYPE Ta yes Ta no Ta yes Ta yes Ta no Ta yes -.It Dv PKCS9STRING_TYPE Ta yes Ta yes Ta yes Ta yes Ta no Ta yes -.El -.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. -.Pp -.Fn ASN1_STRING_set_by_NID -is similar with the following differences: -.Bl -bullet -width 1n -.It -If -.Fa out -is -.Dv NULL , -a new output object is allocated and returned -instead of skipping the copying. -.It -If -.Fa nid -has a global string table entry that can be retrieved with -.Xr ASN1_STRING_TABLE_get 3 , -.Fa mask , -.Fa minchars , -and -.Fa maxchars -are taken from that string table entry. -For some values of -.Fa nid , -an additional global mask is AND'ed into the mask before using it. -The default value of the global mask is -.Dv B_ASN1_UTF8STRING . -.It -If -.Fa nid -has no global string table entry, -.Dv B_ASN1_PRINTABLESTRING | B_ASN1_T61STRING | -.Dv B_ASN1_BMPSTRING | B_ASN1_UTF8STRING -is used instead of the mask taken from the table, -and the global mask is also AND'ed into it. -.It -Even though success and failure happen in the same situations, -the return value is different. -.Xr ASN1_STRING_type 3 -can be used to determine the type of the return value. -.El -.Pp -.Fn ASN1_STRING_set_default_mask -sets the global mask used by -.Fn ASN1_STRING_set_by_NID -to the -.Fa mask -argument. -.Pp -.Fn ASN1_STRING_set_default_mask_asc -sets the global mask as follows: -.Bl -column utf8only -.It Ar maskname Ta Ar mask -.It Qo default Qc Ta anything -.It Qo nombstr Qc Ta anything except Dv B_ASN1_BMPSTRING | B_ASN1_UTF8STRING -.It Qo pkix Qc Ta anything except Dv B_ASN1_T61STRING -.It Qo utf8only Qc Ta Dv B_ASN1_UTF8STRING -.El -.Pp -If the -.Fa maskname -argument starts with the substring -.Qq MASK:\& , -the rest of it is interpreted as an -.Vt unsigned long -value using -.Xr strtoul 3 . -.Pp -.Fn ASN1_tag2bit -translates ASN.1 data types to type bits as follows: -.Bl -column V_ASN1_OBJECT_DESCRIPTOR B_ASN1_UNIVERSALSTRING -.It Fa tag Ta return value -.It Dv V_ASN1_BIT_STRING Ta Dv B_ASN1_BIT_STRING -.It Dv V_ASN1_BMPSTRING Ta Dv B_ASN1_BMPSTRING -.It Dv V_ASN1_BOOLEAN Ta 0 -.It Dv V_ASN1_ENUMERATED Ta Dv B_ASN1_UNKNOWN -.It Dv V_ASN1_EOC Ta 0 -.It Dv V_ASN1_EXTERNAL Ta Dv B_ASN1_UNKNOWN -.It Dv V_ASN1_GENERALIZEDTIME Ta Dv B_ASN1_GENERALIZEDTIME -.It Dv V_ASN1_GENERALSTRING Ta Dv B_ASN1_GENERALSTRING -.It Dv V_ASN1_GRAPHICSTRING Ta Dv B_ASN1_GRAPHICSTRING -.It Dv V_ASN1_IA5STRING Ta Dv B_ASN1_IA5STRING -.It Dv V_ASN1_INTEGER Ta 0 -.It Dv V_ASN1_ISO64STRING Ta Dv B_ASN1_ISO64STRING -.It Dv V_ASN1_NULL Ta 0 -.It Dv V_ASN1_NUMERICSTRING Ta Dv B_ASN1_NUMERICSTRING -.It Dv V_ASN1_OBJECT Ta 0 -.It Dv V_ASN1_OBJECT_DESCRIPTOR Ta Dv B_ASN1_UNKNOWN -.It Dv V_ASN1_OCTET_STRING Ta Dv B_ASN1_OCTET_STRING -.It Dv V_ASN1_PRINTABLESTRING Ta Dv B_ASN1_PRINTABLESTRING -.It Dv V_ASN1_REAL Ta Dv B_ASN1_UNKNOWN -.It Dv V_ASN1_SEQUENCE Ta Dv B_ASN1_SEQUENCE -.It Dv V_ASN1_SET Ta 0 -.It Dv V_ASN1_T61STRING Ta Dv B_ASN1_T61STRING -.It Dv V_ASN1_TELETEXSTRING Ta Dv B_ASN1_TELETEXSTRING -.It Dv V_ASN1_UNDEF Ta 0 -.It Dv V_ASN1_UNIVERSALSTRING Ta Dv B_ASN1_UNIVERSALSTRING -.It Dv V_ASN1_UTCTIME Ta Dv B_ASN1_UTCTIME -.It Dv V_ASN1_UTF8STRING Ta Dv B_ASN1_UTF8STRING -.It Dv V_ASN1_VIDEOTEXSTRING Ta Dv B_ASN1_VIDEOTEXSTRING -.It Dv V_ASN1_VISIBLESTRING Ta Dv B_ASN1_VISIBLESTRING -.It 11, 13, 14, 15, 29 Ta Dv B_ASN1_UNKNOWN -.It Dv other Po < 0, > 30 Pc Ta Dv 0 -.El -.Pp -In typical usage, the calling code calculates the bitwise AND -of the return value and a mask describing data types -that the calling code is willing to use. -If the result of the AND operation is non-zero, the data type is -adequate; otherwise, the calling code may need to raise an error. -.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. -.Pp -.Fn ASN1_STRING_set_by_NID -returns the new or changed ASN.1 string object or -.Dv NULL -on failure. -.Pp -.Fn ASN1_STRING_set_default_mask_asc -returns 1 if successful or 0 if -.Qq MASK:\& -is not followed by a number, if the number is followed by a non-numeric -character, or if the -.Fa maskname -is invalid. -.Pp -.Fn ASN1_STRING_get_default_mask -returns the global mask. -.Pp -.Fn ASN1_tag2bit -returns a -.Dv B_ASN1_* -constant or 0. -.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_UNIVERSALSTRING_to_string 3 -.Sh HISTORY -.Fn ASN1_mbstring_copy , -.Fn ASN1_mbstring_ncopy , -.Fn ASN1_STRING_set_by_NID , -.Fn ASN1_STRING_set_default_mask , -.Fn ASN1_STRING_set_default_mask_asc , -and -.Fn ASN1_STRING_get_default_mask -first appeared in OpenSSL 0.9.5 and have been available since -.Ox 2.7 . -.Pp -.Fn ASN1_tag2bit -first appeared in OpenSSL 0.9.7 and has been available since -.Ox 3.2 . -.Sh BUGS -If integer overflow occurs in -.Fn ASN1_STRING_set_default_mask_asc -while parsing a number following -.Qq MASK:\& , -the function succeeds, essentially behaving in the same way as for -.Qq default . -.Pp -Passing -.Qq default -to -.Fn ASN1_STRING_set_default_mask_asc -does -.Em not -restore the default mask. -Instead, passing -.Qq utf8only -does that. -- cgit v1.2.3-55-g6feb