Describe what ASN1_OBJECT_new(3), ASN1_OBJECT_free(3), OBJ_dup(3),

and OBJ_create(3) really do rather than making broad and incomplete
statements that are only true in some cases.

Improve the one-line descriptions.
Some minor wording improvements while here.

There is obviously more work to do in the vicinity...

2 files changed, 105 insertions, 34 deletions

diff --git a/lib/libcrypto/man/ASN1_OBJECT_new.3 b/lib/libcrypto/man/ASN1_OBJECT_new.3
index 55a90bbcb25..e7c3540b3a8 100644
--- a/lib/libcrypto/man/ASN1_OBJECT_new.3
+++ b/lib/libcrypto/man/ASN1_OBJECT_new.3
@@ -1,7 +1,24 @@
-.\"	$OpenBSD: ASN1_OBJECT_new.3,v 1.7 2016/11/10 14:34:18 jmc Exp $
+.\"	$OpenBSD: ASN1_OBJECT_new.3,v 1.8 2017/01/04 05:14:51 schwarze Exp $
 .\"	OpenSSL 99d63d4 Mar 19 12:28:58 2016 -0400
 .\"
-.\" This file was written by Dr. Stephen Henson.
+.\" 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.
 .\" Copyright (c) 2002, 2006 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,13 +65,13 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 10 2016 $
+.Dd $Mdocdate: January 4 2017 $
 .Dt ASN1_OBJECT_NEW 3
 .Os
 .Sh NAME
 .Nm ASN1_OBJECT_new ,
 .Nm ASN1_OBJECT_free
-.Nd ASN.1 object allocation functions
+.Nd ASN.1 object identifiers
 .Sh SYNOPSIS
 .In openssl/asn1.h
 .Ft ASN1_OBJECT *
@@ -66,34 +83,45 @@
 .Fa "ASN1_OBJECT *a"
 .Fc
 .Sh DESCRIPTION
-The ASN1_OBJECT allocation routines allocate and free an
+.Fn ASN1_OBJECT_new
+allocates and initializes an empty
 .Vt ASN1_OBJECT
-structure, which represents an ASN.1 OBJECT IDENTIFIER.
+object, representing an ASN.1 OBJECT IDENTIFIER.
+It can hold a short name, a long name, a numeric identifier (NID),
+and a sequence of integers identifying a node in the International
+Object Identifier tree as specified in ITU-T recommendation X.660.
+The new object is marked as dynamically allocated.
 .Pp
+Application programs normally use utility functions like
+.Xr OBJ_nid2obj 3
+rather than using
 .Fn ASN1_OBJECT_new
-allocates and initializes an
-.Vt ASN1_OBJECT
-structure.
+directly.
 .Pp
 .Fn ASN1_OBJECT_free
-frees up the
-.Vt ASN1_OBJECT
-structure
-.Fa a .
+has the following effects:
+.Pp
+All data contained in
+.Fa a
+that is marked as dynamically allocated is freed,
+and the respective fields of
+.Fa a
+become empty.
+Contained data not marked as dynamically allocated remains intact.
+.Pp
+If the object
+.Fa a
+itself is marked as dynamically allocated, it is freed.
+Otherwise, the pointer
+.Fa a
+remains valid.
+.Pp
 If
 .Fa a
 is a
 .Dv NULL
-pointer, no action occurs.
-.Pp
-Although
-.Fn ASN1_OBJECT_new
-allocates a new
-.Vt ASN1_OBJECT
-structure, it is almost never used in applications.
-The ASN.1 object utility functions such as
-.Xr OBJ_nid2obj 3
-are used instead.
+pointer or if neither the object itself nor any of its content
+is marked as dynamically allocated, no action occurs.
 .Sh RETURN VALUES
 If the allocation fails,
 .Fn ASN1_OBJECT_new
@@ -101,10 +129,9 @@ returns
 .Dv NULL
 and sets an error code that can be obtained by
 .Xr ERR_get_error 3 .
-Otherwise it returns a pointer to the newly allocated structure.
+Otherwise it returns a pointer to the new object.
 .Sh SEE ALSO
 .Xr d2i_ASN1_OBJECT 3 ,
-.Xr ERR_get_error 3 ,
 .Xr OBJ_nid2obj 3
 .Sh HISTORY
 .Fn ASN1_OBJECT_new
diff --git a/lib/libcrypto/man/OBJ_nid2obj.3 b/lib/libcrypto/man/OBJ_nid2obj.3
index 61838317845..5fa3e6fa7a7 100644
--- a/lib/libcrypto/man/OBJ_nid2obj.3
+++ b/lib/libcrypto/man/OBJ_nid2obj.3
@@ -1,7 +1,24 @@
-.\"	$OpenBSD: OBJ_nid2obj.3,v 1.4 2016/11/27 18:22:25 schwarze Exp $
+.\"	$OpenBSD: OBJ_nid2obj.3,v 1.5 2017/01/04 05:14:51 schwarze Exp $
 .\"	OpenSSL c264592d May 14 11:28:00 2006 +0000
 .\"
-.\" 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) 2002, 2006, 2015, 2016 The OpenSSL Project.
 .\" All rights reserved.
 .\"
@@ -49,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: November 27 2016 $
+.Dd $Mdocdate: January 4 2017 $
 .Dt OBJ_NID2OBJ 3
 .Os
 .Sh NAME
@@ -67,7 +84,7 @@
 .Nm OBJ_create ,
 .Nm OBJ_cleanup ,
 .Nm i2t_ASN1_OBJECT
-.Nd ASN.1 object utility functions
+.Nd inspect and create ASN.1 object identifiers
 .Sh SYNOPSIS
 .In openssl/objects.h
 .Ft ASN1_OBJECT *
@@ -225,8 +242,20 @@ to
 If the two are identical, 0 is returned.
 .Pp
 .Fn OBJ_dup
-returns a copy of
-.Fa o .
+returns a deep copy of
+.Fa o
+if
+.Fa o
+is marked as dynamically allocated.
+The new object and all data contained in it is marked as dynamically
+allocated.
+If
+.Fa o
+is not marked as dynamically allocated,
+.Fn OBJ_dup
+just returns
+.Fa o
+itself.
 .Pp
 .Fn OBJ_create
 adds a new object to the internal table.
@@ -238,6 +267,14 @@ the short name and
 the long name.
 A new NID is returned for the created object.
 .Pp
+The new object added to the internal table and all the data
+contained in it is marked as not dynamically allocated.
+Consequently, retrieving it with
+.Fn OBJ_nid2obj
+or a similar function and then calling
+.Xr ASN1_OBJECT_free 3
+on the returned pointer will have no effect.
+.Pp
 .Fn OBJ_cleanup
 cleans up the internal object table: this should be called before
 an application exits if any new objects were added using
@@ -275,11 +312,13 @@ and
 can process the numerical form of an OID.
 .Sh RETURN VALUES
 .Fn OBJ_nid2obj
-returns an
+and
+.Fn OBJ_dup
+return an
 .Vt ASN1_OBJECT
-structure or
+object or
 .Dv NULL
-if an error occurred.
+if an error occurs.
 .Pp
 .Fn OBJ_nid2ln
 and
@@ -296,6 +335,11 @@ and
 return a NID or
 .Dv NID_undef
 on error.
+.Pp
+.Fn OBJ_create
+returns the new NID or
+.Dv NID_undef
+if an error occurs.
 .Sh EXAMPLES
 Create an object for
 .Sy commonName :