document OBJ_new_nid(3), OBJ_add_object(3), and OBJ_create_objects(3);

mark OBJ_create_and_add_object() as intentionally undocumented

1 files changed, 91 insertions, 9 deletions

diff --git a/src/lib/libcrypto/man/OBJ_create.3 b/src/lib/libcrypto/man/OBJ_create.3
index 37a3907193..e79ef90853 100644
--- a/src/lib/libcrypto/man/OBJ_create.3
+++ b/src/lib/libcrypto/man/OBJ_create.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: OBJ_create.3,v 1.1 2021/12/15 20:07:51 schwarze Exp $
+.\" $OpenBSD: OBJ_create.3,v 1.2 2021/12/15 22:20:12 schwarze Exp $
 .\" full merge up to:
 .\" OpenSSL OBJ_nid2obj.pod 9b86974e Aug 17 15:21:33 2015 -0400
 .\" selective merge up to:
@@ -73,33 +73,77 @@
 .Dt OBJ_CREATE 3
 .Os
 .Sh NAME
+.Nm OBJ_new_nid ,
+.Nm OBJ_add_object ,
 .Nm OBJ_create ,
+.\" OBJ_create_and_add_object is a deprecated, unused alias for OBJ_create(3).
+.Nm OBJ_create_objects ,
 .Nm OBJ_cleanup
 .Nd modify the table of ASN.1 object identifiers
 .Sh SYNOPSIS
 .In openssl/objects.h
 .Ft int
+.Fn OBJ_new_nid "int increment"
+.Ft int
+.Fn OBJ_add_object "const ASN1_OBJECT *object"
+.Ft int
 .Fo OBJ_create
 .Fa "const char *oid"
 .Fa "const char *sn"
 .Fa "const char *ln"
 .Fc
+.Ft int
+.Fn OBJ_create_objects "BIO *in_bio"
 .Ft void
 .Fn OBJ_cleanup void
 .Sh DESCRIPTION
+.Fn OBJ_new_nid
+returns the smallest currently unassigned ASN.1 numeric
+object identifier (NID) and reserves
+.Fa increment
+consecutive NIDs starting with it.
+Passing an argument of 1 is usually recommended.
+The return value can be assigned to a new object by passing it as the
+.Fa nid
+argument to
+.Xr ASN1_OBJECT_create 3
+and by passing the resulting object to
+.Fn OBJ_add_object .
+.Pp
+.Fn OBJ_add_object
+adds a copy of the
+.Fa object
+to the internal table of ASN.1 object identifiers for use by
+.Xr OBJ_nid2obj 3
+and related functions.
+.Pp
 .Fn OBJ_create
-adds a new object to the internal table.
+provides a simpler way to add a new object to the internal table.
 .Fa oid
 is the numerical form of the object,
 .Fa sn
 the short name and
 .Fa ln
 the long name.
-A new NID is returned for the created object.
+A new NID is automatically assigned using
+.Fn OBJ_new_nid .
+.Pp
+.Fn OBJ_create_objects
+reads text lines of the form
+.Pp
+.D1 Fa oid sn ln
+.Pp
+from
+.Fa in_bio
+and calls
+.Fn OBJ_create oid sn ln
+for every line read.
+The three fields of the input lines
+are separated by one or more whitespace characters.
 .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
+For all three functions, the objects added to the internal table and
+all the data contained in them is marked as not dynamically allocated.
+Consequently, retrieving them with
 .Xr OBJ_nid2obj 3
 or a similar function and then calling
 .Xr ASN1_OBJECT_free 3
@@ -108,23 +152,45 @@ on the returned pointer will have no effect.
 .Fn OBJ_cleanup
 cleans up the internal object table: this should be called before
 an application exits if any new objects were added using
-.Fn OBJ_create .
+.Fn OBJ_add_object ,
+.Fn OBJ_create ,
+or
+.Fn OBJ_create_objects .
 .Sh RETURN VALUES
+.Fn OBJ_new_nid
+returns the new NID.
+.Pp
+.Fn OBJ_add_object
+returns the NID associated with the
+.Fa object
+or
+.Dv NID_undef
+if memory allocation fails.
+.Pp
 .Fn OBJ_create
 returns the new NID or
 .Dv NID_undef
-if an error occurs.
+if
+.Fa oid
+is not a valid representation of an object identfier
+or if memory allocation fails.
+.Pp
+.Fn OBJ_create_objects
+returns the number of objects added.
 .Pp
 In some cases of failure of
+.Fn OBJ_add_object ,
 .Fn OBJ_create ,
+and
+.Fn OBJ_create_objects ,
 the reason can be determined with
 .Xr ERR_get_error 3 .
 .Sh EXAMPLES
 Create a new NID and initialize an object from it:
 .Bd -literal -offset indent
 int new_nid;
-
 ASN1_OBJECT *obj;
+
 new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
 obj = OBJ_nid2obj(new_nid);
 .Ed
@@ -132,9 +198,25 @@ obj = OBJ_nid2obj(new_nid);
 .Xr ASN1_OBJECT_new 3 ,
 .Xr OBJ_nid2obj 3
 .Sh HISTORY
+.Fn OBJ_new_nid ,
+.Fn OBJ_add_object ,
+and
 .Fn OBJ_cleanup
 first appeared in SSLeay 0.8.0 and
 .Fn OBJ_create
 in SSLeay 0.9.0.
 These functions have been available since
 .Ox 2.4 .
+.Sh BUGS
+.Fn OBJ_new_nid
+does not reserve any return value to indicate an error.
+Consequently, to avoid conflicting NID assignments and integer overflows,
+care must be taken to not pass negative, zero, or large arguments to
+.Fn OBJ_new_nid .
+.Pp
+.Fn OBJ_create_objects
+does not distinguish between end of file, I/O errors, temporary
+unavailability of data on a non-blocking BIO, invalid input syntax,
+and memory allocation failure.
+In all these cases, reading is aborted and the number of objects
+that were already added is returned.