NOTES
Objects in OpenSSL can have a short name, a long name and a numerical identifier (NID) associated with them. A standard set of objects is represented in an internal table. The appropriate values are defined in the header file objects.h.
For example the OID for commonName has the following definitions:
#define SN_commonName "CN"
#define LN_commonName "commonName"
#define NID_commonName 13
New objects can be added by calling OBJ_create().
Table objects have certain advantages over other objects: for example their NIDs can be used in a C language switch statement. They are also static constant structures which are shared: that is there is only a single constant structure for each table object.
Objects which are not in the table have the NID value NID_undef.
Objects do not need to be in the internal tables to be processed, the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical form of an OID.
Some objects are used to represent algorithms which do not have a corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently exists for a particular algorithm). As a result they cannot be encoded or decoded as part of ASN.1 structures. Applications can determine if there is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero.
These functions cannot return const because an ASN1_OBJECT can represent both an internal, constant, OID and a dynamically-created one. The latter cannot be constant because it needs to be freed after use.
EXAMPLES
Create an object for commonName:
ASN1_OBJECT *o;
o = OBJ_nid2obj(NID_commonName);
Check if an object is commonName
if (OBJ_obj2nid(obj) == NID_commonName)
/* Do something */
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);
Create a new object directly:
obj = OBJ_txt2obj("1.2.3.4", 1);
BUGS
OBJ_obj2txt() is awkward and messy to use: it doesn't follow the convention of other OpenSSL functions where the buffer can be set to NULL to determine the amount of data that should be written. Instead buf must point to a valid buffer and buf_len should be set to a positive value. A buffer length of 80 should be more than enough to handle any OID encountered in practice.
RETURN VALUES
OBJ_nid2obj() returns an ASN1_OBJECT structure or NULL is an error occurred.
OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or NULL on error.
OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return a NID or NID_undef on error.
SEE ALSO
HISTORY
OBJ_cleanup() was deprecated in OpenSSL 1.1.0.
COPYRIGHT
Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.