From fff8af46ac88307060ab4cbdda99dab49bfa1728 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Tue, 3 Jan 2017 20:15:47 +0000 Subject: Document ASN1_TYPE_new(3) and ASN1_TYPE_free(3), even though OpenSSL does not document them. By being in <openssl/asn1.h>, they are public, and it makes no sense to document accessors but not document constructors and destructors. Improve the one-line description. Mention various missing details. Many wording improvements. Add some cross references. --- src/lib/libcrypto/man/ASN1_TYPE_get.3 | 134 ++++++++++++++++++++++++++-------- src/lib/libcrypto/man/ASN1_item_new.3 | 6 +- 2 files changed, 106 insertions(+), 34 deletions(-) (limited to 'src') diff --git a/src/lib/libcrypto/man/ASN1_TYPE_get.3 b/src/lib/libcrypto/man/ASN1_TYPE_get.3 index 5531e572d1..47ea1cdfc6 100644 --- a/src/lib/libcrypto/man/ASN1_TYPE_get.3 +++ b/src/lib/libcrypto/man/ASN1_TYPE_get.3 @@ -1,7 +1,24 @@ -.\" $OpenBSD: ASN1_TYPE_get.3,v 1.2 2016/11/12 19:23:16 jmc Exp $ +.\" $OpenBSD: ASN1_TYPE_get.3,v 1.3 2017/01/03 20:15:47 schwarze Exp $ .\" OpenSSL 99d63d46 Mon Jun 6 00:43:05 2016 -0400 .\" -.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2017 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. +.\" +.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. .\" Copyright (c) 2015, 2016 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -48,17 +65,23 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: November 12 2016 $ +.Dd $Mdocdate: January 3 2017 $ .Dt ASN1_TYPE_GET 3 .Os .Sh NAME +.Nm ASN1_TYPE_new , +.Nm ASN1_TYPE_free , .Nm ASN1_TYPE_get , .Nm ASN1_TYPE_set , .Nm ASN1_TYPE_set1 , .Nm ASN1_TYPE_cmp -.Nd ASN1_TYPE utility functions +.Nd ASN.1 objects of arbitrary type .Sh SYNOPSIS .In openssl/asn1.h +.Ft ASN1_TYPE * +.Fn ASN1_TYPE_new void +.Ft void +.Fn ASN1_TYPE_free "ASN1_TYPE *a" .Ft int .Fo ASN1_TYPE_get .Fa "ASN1_TYPE *a" @@ -81,20 +104,41 @@ .Fa "ASN1_TYPE *b" .Fc .Sh DESCRIPTION -These functions manipulate .Vt ASN1_TYPE -structures. +represents the ASN.1 ANY type. An .Vt ASN1_TYPE -structure can contain any ASN.1 type or constructed type such as a -SEQUENCE: it is effectively equivalent to the ASN.1 ANY type. +object can store an ASN.1 value of arbitrary type, +including constructed types such as a SEQUENCE. +It also remembers internally which type it currently holds. +.Pp +.Fn ASN1_TYPE_new +allocates and initializes an empty +.Vt ASN1_TYPE +object of undefined type. +.Pp +.Fn ASN1_TYPE_free +frees +.Fa a +including the value stored in it, if any. +If +.Fa a +is a +.Dv NULL +pointer, no action occurs. .Pp .Fn ASN1_TYPE_get returns the type of -.Fa a . +.Fa a , +represented by one of the +.Dv V_ASN1_* +constants defined in +.In openssl/asn1.h . .Pp .Fn ASN1_TYPE_set -sets the value of +frees the value contained in +.Fa a , +if any, and sets .Fa a to .Fa type @@ -107,28 +151,28 @@ internally so it must be freed up after the call. .Pp .Fn ASN1_TYPE_set1 -sets the value of +sets the type of .Fa a to .Fa type -and a copy of +and its value to a copy of .Fa value . -.Pp -.Fn ASN1_TYPE_cmp -compares ASN.1 types +If copying succeeds, the previous value that was contained in .Fa a -and -.Fa b . +is freed. +If copying fails, +.Fa a +remains unchanged. .Pp The type and meaning of the .Fa value -parameter for +argument of .Fn ASN1_TYPE_set and .Fn ASN1_TYPE_set1 is determined by the .Fa type -parameter. +argument. If .Fa type is @@ -173,19 +217,26 @@ contains the entire ASN.1 encoding verbatim, including tag and length octets. .Pp .Fn ASN1_TYPE_cmp -may not return zero if two types are equivalent but have different -encodings. -For example the single content octet of the boolean TRUE value under BER -can have any non-zero encoding but +checks that +.Fa a +and +.Fa b +have the same type, the same value, and are encoded in the same way. +.Pp +If the types agree and the values have the same meaning but are +encoded differently, they are considered different. +For example, a boolean value is represented +using a single content octet. +Under BER, any non-zero octet represents the TRUE value, but .Fn ASN1_TYPE_cmp -will only return zero if the values are the same. +will only report a match if the content octet is the same. .Pp -If either or both of the parameters passed to +If either or both of the arguments passed to .Fn ASN1_TYPE_cmp is .Dv NULL , -the return value is non-zero. -Technically, if both parameters are +the result is a mismatch. +Technically, if both arguments are .Dv NULL , the two types could be absent OPTIONAL fields and so should match, however passing @@ -198,13 +249,32 @@ for types which do match. So applications should handle the case of two absent values separately. .Sh RETURN VALUES -.Fn ASN1_TYPE_get -returns the type of the +.Fn ASN1_TYPE_new +returns the new .Vt ASN1_TYPE -argument. +object or +.Dv NULL +if an error occurs. +.Pp +.Fn ASN1_TYPE_get +returns the type of +.Fa a +or 0 if an error occurs. +The latter can happen if +.Fa a +does not contain a value even though its type is not +.Dv V_ASN1_NULL . +For example, it will always happen for empty objects +newly constructed with +.Fn ASN1_TYPE_new . .Pp .Fn ASN1_TYPE_set1 -returns 1 for success or 0 for failure. +returns 1 if the copying succeeds or 0 if it fails. .Pp .Fn ASN1_TYPE_cmp -returns 0 if the types are identical or non-zero otherwise. +returns 0 for a match or non-zero for a mismatch. +.Sh SEE ALSO +.Xr ASN1_item_free 3 , +.Xr ASN1_STRING_dup 3 , +.Xr d2i_ASN1_TYPE 3 , +.Xr OBJ_dup 3 diff --git a/src/lib/libcrypto/man/ASN1_item_new.3 b/src/lib/libcrypto/man/ASN1_item_new.3 index 0444bbe15a..e679815751 100644 --- a/src/lib/libcrypto/man/ASN1_item_new.3 +++ b/src/lib/libcrypto/man/ASN1_item_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ASN1_item_new.3,v 1.1 2016/12/24 21:42:29 schwarze Exp $ +.\" $OpenBSD: ASN1_item_new.3,v 1.2 2017/01/03 20:15:47 schwarze Exp $ .\" .\" Copyright (c) 2016 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: December 24 2016 $ +.Dd $Mdocdate: January 3 2017 $ .Dt ASN1_ITEM_NEW 3 .Os .Sh NAME @@ -95,6 +95,8 @@ object or if an error occurs. .Sh SEE ALSO .Xr ASN1_item_d2i 3 , +.Xr ASN1_TYPE_new 3 , +.Xr d2i_ASN1_NULL 3 , .Xr OBJ_nid2obj 3 .Sh BUGS The -- cgit v1.2.3-55-g6feb