NAME

OBJ_new_nid, OBJ_add_object, OBJ_create, OBJ_create_objects, obj_cleanup_defer, OBJ_cleanup, check_defer — modify the table of ASN.1 object identifiers

SYNOPSIS

#include <openssl/objects.h> int
OBJ_new_nid(int increment); int
OBJ_add_object(const ASN1_OBJECT *object); int
OBJ_create(const char *oid, const char *sn, const char *ln); int
OBJ_create_objects(BIO *in_bio); extern int obj_cleanup_defer; void
OBJ_cleanup(void); void
check_defer(int nid);

DESCRIPTION

OBJ_new_nid() returns the smallest currently unassigned ASN.1 numeric object identifier (NID) and reserves 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 nid argument to ASN1_OBJECT_create(3) and by passing the resulting object to OBJ_add_object(). OBJ_add_object() adds a copy of the object to the internal table of ASN.1 object identifiers for use by OBJ_nid2obj(3) and related functions. OBJ_create() provides a simpler way to add a new object to the internal table. oid is the numerical form of the object, sn the short name and ln the long name. A new NID is automatically assigned using OBJ_new_nid(). OBJ_create_objects() reads text lines of the form

oid sn ln

from in_bio and calls OBJ_create(oid, sn, ln) for every line read. The three fields of the input lines are separated by one or more whitespace characters. 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 OBJ_nid2obj(3) or a similar function and then calling ASN1_OBJECT_free(3) on the returned pointer will have no effect. The global variable obj_cleanup_defer controls the behaviour of OBJ_cleanup() and EVP_cleanup(3). If obj_cleanup_defer has the default value of 0, OBJ_cleanup() resets the internal object table to its default state, removing and freeing all objects that were added with OBJ_add_object(), OBJ_create(), or OBJ_create_objects(). Otherwise, OBJ_cleanup() only sets obj_cleanup_defer to 2, which defers the cleanup of the internal object table to the next call of EVP_cleanup(3). By default, EVP_cleanup(3) has no effect on the internal object table. Only if obj_cleanup_defer is 2, it resets obj_cleanup_defer to 0 and calls OBJ_cleanup(), which then resets the table to its default state. The function check_defer() sets obj_cleanup_defer to 1 unless nid is a built-in numeric identifier, but it has no effect if obj_cleanup_defer already differs from 0. This function is called internally by various functions in the EVP library, in particular by subroutines of OpenSSL_add_all_ciphers(3) and OpenSSL_add_all_digests(3). To reliably reset the internal object table no matter what the current state may be, an application program needs to call both OBJ_cleanup() and EVP_cleanup(3), in this order. The opposite order will usually not work.

RETURN VALUES

OBJ_new_nid() returns the new NID. OBJ_add_object() returns the NID associated with the object or NID_undef if memory allocation fails. OBJ_create() returns the new NID or NID_undef if oid is not a valid representation of an object identifier or if memory allocation fails. OBJ_create_objects() returns the number of objects added. In some cases of failure of OBJ_add_object(), OBJ_create(), and OBJ_create_objects(), the reason can be determined with ERR_get_error(3).

EXAMPLES

Create a new NID and initialize an object from it:

int new_nid; 
ASN1_OBJECT *obj; 
 
new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); 
obj = OBJ_nid2obj(new_nid);

SEE ALSO

ASN1_OBJECT_new(3), EVP_cleanup(3), OBJ_add_sigid(3), OBJ_NAME_add(3), OBJ_nid2obj(3)

HISTORY

OBJ_new_nid(), OBJ_add_object(), and OBJ_cleanup() first appeared in SSLeay 0.8.0 and OBJ_create() in SSLeay 0.9.0. These functions have been available since OpenBSD 2.4. obj_cleanup_defer and check_defer() first appeared in OpenSSL 1.0.0 and have been available since OpenBSD 4.9.

BUGS

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 OBJ_new_nid(). 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.