From: schwarze Date: Wed, 15 Dec 2021 22:20:12 +0000 (+0000) Subject: document OBJ_new_nid(3), OBJ_add_object(3), and OBJ_create_objects(3); X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=3d99ce21cbc959c23b153198634da3eb126927f6;p=openbsd document OBJ_new_nid(3), OBJ_add_object(3), and OBJ_create_objects(3); mark OBJ_create_and_add_object() as intentionally undocumented --- diff --git a/lib/libcrypto/man/OBJ_create.3 b/lib/libcrypto/man/OBJ_create.3 index 37a39071936..e79ef90853c 100644 --- a/lib/libcrypto/man/OBJ_create.3 +++ b/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.