The ASN1 object utility functions process ASN1_OBJECT structures which are
a representation of the ASN1 OBJECT IDENTIFIER (OID) type.
-For convenience, OID's are usually represented in source code as numeric
-identifiers, or B<NID>'s. OpenSSL has an internal table of OID's that
-are generated when the library is built, and their corresponding NID's
-are available as define'd constants. For the functions below, application
-code should treat all returned values -- OID's, NID's, or names -- as
+For convenience, OIDs are usually represented in source code as numeric
+identifiers, or B<NID>s. OpenSSL has an internal table of OIDs that
+are generated when the library is built, and their corresponding NIDs
+are available as defined constants. For the functions below, application
+code should treat all returned values -- OIDs, NIDs, or names -- as
constants.
OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to
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 B<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 B<const> because an B<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.
+
=head1 EXAMPLES
Create an object for B<commonName>:
Check if an object is B<commonName>
if (OBJ_obj2nid(obj) == NID_commonName)
- /* Do something */
+ /* Do something */
Create a new NID and initialize an object from it:
be set to a positive value. A buffer length of 80 should be more
than enough to handle any OID encountered in practice.
-Many of the functions here should probably be changed to return B<const>
-pointers. But the lack of consistency makes that too awkward to do.
-
=head1 RETURN VALUES
OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an
error occurred.
+It returns a pointer to an internal table and does not
+allocate memory; ASN1_OBJECT_free() will have no effect.
OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
on error.