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.

2 files changed, 106 insertions, 34 deletions

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