From: schwarze Date: Mon, 12 Feb 2018 15:45:12 +0000 (+0000) Subject: Add the missing RETURN VALUES section and reorder the content X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=7186df292f4817a0519368d27276660687167aab;p=openbsd Add the missing RETURN VALUES section and reorder the content accordingly. Make some statements more precise, and point out some dangerous traps in these ill-designed interfaces. Also do some minor polishing while here. Triggered by OpenSSL commit 1f13ad31 Dec 25 17:50:39 2017 +0800 by Paul Yang, but not using most of his wording because that is in part redundant, in part incomplete, and in part outright wrong. --- diff --git a/lib/libcrypto/man/ASN1_STRING_length.3 b/lib/libcrypto/man/ASN1_STRING_length.3 index 2c797481d71..398d49eee47 100644 --- a/lib/libcrypto/man/ASN1_STRING_length.3 +++ b/lib/libcrypto/man/ASN1_STRING_length.3 @@ -1,8 +1,26 @@ -.\" $OpenBSD: ASN1_STRING_length.3,v 1.6 2016/12/25 22:15:10 schwarze Exp $ -.\" OpenSSL 99d63d46 Tue Jun 21 07:03:34 2016 -0400 +.\" $OpenBSD: ASN1_STRING_length.3,v 1.7 2018/02/12 15:45:12 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Tue Jun 21 07:03:34 2016 -0400 +.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 .\" -.\" This file was written by Dr. Stephen Henson. -.\" Copyright (c) 2002, 2006, 2013, 2015, 2016 The OpenSSL Project. +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018 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. +.\" +.\" The original file was written by Dr. Stephen Henson. +.\" Copyright (c) 2002, 2006, 2013, 2015, 2016, 2017 The OpenSSL Project. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -49,7 +67,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 25 2016 $ +.Dd $Mdocdate: February 12 2018 $ .Dt ASN1_STRING_LENGTH 3 .Os .Sh NAME @@ -107,27 +125,24 @@ These functions manipulate structures. .Pp .Fn ASN1_STRING_cmp -compares +compares the type, the length, and the content of .Fa a and -.Fa b -and returns 0 if the two are identical. -The string types and the content are compared. +.Fa b . .Pp .Fn ASN1_STRING_data returns an internal pointer to the data of .Fa x . -Since this is an internal pointer, it should -.Em not -be freed or modified in any way. +It should not be freed or modified in any way. .Pp .Fn ASN1_STRING_dup -returns a copy of the structure +copies .Fa a . .Pp .Fn ASN1_STRING_length -returns the length of the content of -.Fa x . +returns the length attribute of +.Fa x , +measured in bytes. .Pp .Fn ASN1_STRING_length_set sets the length attribute of @@ -139,39 +154,46 @@ It may put into an inconsistent internal state. .Pp .Fn ASN1_STRING_set -sets the data of the string +sets the length attribute of .Fa str -to the buffer +to +.Fa len +and copies that number of bytes from .Fa data -of length +into +.Fa str . +If +.Fa len +is -1, then +.Fn strlen data +is used instead of .Fa len . -The supplied data is copied. If +.Fa data +is +.Dv NULL , +the content of +.Fa str +remains uninitialized; that is not considered an error unless .Fa len -is -1 then the length is determined by -.Fn strlen data . +is negative. .Pp .Fn ASN1_STRING_to_UTF8 converts the string .Fa in -to UTF8 format. +to UTF-8 format. The converted data is copied into a newly allocated buffer -.Fa out . -The length of -.Fa out -is returned or a negative error code. +.Pf * Fa out . The buffer -.Fa out +.Pf * Fa out should be freed using .Xr free 3 . .Pp .Fn ASN1_STRING_type returns the type of -.Fa x , -using standard constants such as -.Dv V_ASN1_OCTET_STRING . +.Fa x . .Pp -Almost all ASN.1 types in OpenSSL are represented as +Almost all ASN.1 types are represented as .Vt ASN1_STRING structures. Other types such as @@ -200,17 +222,53 @@ be used instead. In general it cannot be assumed that the data returned by .Fn ASN1_STRING_data is NUL terminated, and it may contain embedded NUL characters. -The actual format of the data will depend on the actual string type itself: +The format of the data depends on the string type: for example for an .Vt IA5String -the data will be ASCII, for a +the data contains ASCII characters, a .Vt BMPString two bytes per character in big endian format, and a .Vt UTF8String -will be in UTF8 format. +UTF-8 characters. .Pp -Similar care should be take to ensure the data is in the correct format +Similar care should be taken to ensure the data is in the correct format when calling .Fn ASN1_STRING_set . +.Sh RETURN VALUES +.Fn ASN1_STRING_cmp +returns 0 if the type, the length, and the content of +.Fa a +and +.Fa b +agree, or a non-zero value otherwise. +In contrast to +.Xr strcmp 3 , +the sign of the return value does not indicate lexicographical ordering. +.Pp +.Fn ASN1_STRING_data +returns an internal pointer to the data of +.Fa x . +.Pp +.Fn ASN1_STRING_dup +returns a pointer to a newly allocated +.Vt ASN1_STRING +structure or +.Dv NULL +if an error occurred. +.Pp +.Fn ASN1_STRING_length +returns a number of bytes. +.Pp +.Fn ASN1_STRING_set +returns 1 on success or 0 on failure. +.Pp +.Fn ASN1_STRING_to_UTF8 +returns the number of bytes in the output buffer +.Pf * Fa out , +or a negative number if an error occurred. +.Pp +.Fn ASN1_STRING_type +returns an integer constant, for example +.Dv V_ASN1_OCTET_STRING . .Sh SEE ALSO .Xr ERR_get_error 3