--- name: "libressl-OBJ_nid2obj" section: "3" platform: "linux" package: "libressl" version: "4.4.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/libressl-OBJ_nid2obj" --- # libressl-OBJ\_nid2obj(3) inspect and create ASN.1 object identifiers ## NAME **OBJ\_nid2obj**, **OBJ\_nid2ln**, **OBJ\_nid2sn**, **OBJ\_obj2nid**, **OBJ\_ln2nid**, **OBJ\_sn2nid**, **OBJ\_txt2nid**, **OBJ\_txt2obj**, **OBJ\_obj2txt**, **OBJ\_cmp**, **OBJ\_dup**, **i2t\_ASN1\_OBJECT**, **i2a\_ASN1\_OBJECT** – inspect and create ASN.1 object identifiers ## SYNOPSIS Crypto Library (libcrypto, -lcrypto) **#include \** *ASN1\_OBJECT* *\**\ **OBJ\_nid2obj**(*int nid*); *const* *char* *\**\ **OBJ\_nid2ln**(*int nid*); *const* *char* *\**\ **OBJ\_nid2sn**(*int nid*); *int*\ **OBJ\_obj2nid**(*const ASN1\_OBJECT \*object*); *int*\ **OBJ\_ln2nid**(*const char \*ln*); *int*\ **OBJ\_sn2nid**(*const char \*sn*); *int*\ **OBJ\_txt2nid**(*const char \*s*); *ASN1\_OBJECT* *\**\ **OBJ\_txt2obj**(*const char \*s*, *int no\_name*); *int*\ **OBJ\_obj2txt**(*char \*buf*, *int buf\_len*, *const ASN1\_OBJECT \*object*, *int no\_name*); *int*\ **OBJ\_cmp**(*const ASN1\_OBJECT \*a*, *const ASN1\_OBJECT \*b*); *ASN1\_OBJECT* *\**\ **OBJ\_dup**(*const ASN1\_OBJECT \*object*); **#include \** *int*\ **i2t\_ASN1\_OBJECT**(*char \*buf*, *int buf\_len*, *const ASN1\_OBJECT \*object*); *int*\ **i2a\_ASN1\_OBJECT**(*BIO \*out\_bio*, *const ASN1\_OBJECT \*object*); ## DESCRIPTION The ASN.1 object utility functions process *ASN1\_OBJECT* structures, in the following called “objects”. An object represents an ASN.1 *OBJECT* *IDENTIFIER* (OID). The library maintains an internal global table of objects. Many of these objects are built into the library and contained in the global table by default. The application program can add additional objects to the global table by using functions documented in the OBJ\_create(3) manual page. Consequently, there are three classes of objects: built-in table objects, user-defined table objects, and non-table objects. In addition to the OID, each object can hold a long name, a short name, and a numerical identifier (NID). Even though the concept of NIDs is specific to the library and not standardized, using the NID is often the most convenient way for source code to refer to a specific OID. The NIDs of the built-in objects are available as defined constants. Built-in table objects have certain advantages over objects that are not in the global table: for example, their NIDs can be used in C language switch statements. They are also shared: there is only a single static constant structure for each built-on OID. Some functions operate on table objects only: **OBJ\_nid2obj**() retrieves the table object associated with the *nid*. **OBJ\_nid2ln**() and **OBJ\_nid2sn**() retrieve its long and short name, respectively. **OBJ\_obj2nid**() retrieves the NID associated with the given *object*, which is either the NID stored in the *object* itself, if any, or otherwise the NID stored in a table object containing the same OID. **OBJ\_ln2nid**() and **OBJ\_sn2nid**() retrieve the NID from the table object with the long name *ln* or the short name *sn*, respectively. **OBJ\_txt2nid**() retrieves the NID from the table object described by the text string *s*, which can be a long name, a short name, or the numerical representation of an OID. The remaining functions can be used both on table objects and on objects that are not in the global table: **OBJ\_txt2obj**() retrieves or creates an object matching the text string *s*. If *no\_name* is 1, only the numerical representation of an OID is accepted. If *no\_name* is 0, long names and short names are accepted as well. **OBJ\_obj2txt**() writes a NUL terminated textual representation of the OID contained in the given *object* into *buf*. At most *buf\_len* bytes are written, truncating the result if necessary. The total amount of space required is returned. If *no\_name* is 0 and the table object containing the same OID contains a long name, the long name is written. Otherwise, if *no\_name* is 0 and the table object containing the same OID contains a short name, the short name is written. Otherwise, the numerical representation of the OID is written. **i2t\_ASN1\_OBJECT**() is the same as **OBJ\_obj2txt**() with *no\_name* set to 0. **i2a\_ASN1\_OBJECT**() writes a textual representation of the OID contained in the given *object* to *out\_bio* using BIO\_write(3). It does not write a terminating NUL byte. If the *object* argument is NULL or contains no OID, it writes the 4-byte string "NULL". If **i2t\_ASN1\_OBJECT**() fails, **i2a\_ASN1\_OBJECT**() writes the 9-byte string "\". Otherwise, it writes the string constructed with **i2t\_ASN1\_OBJECT**(). **OBJ\_cmp**() tests whether *a* and *b* represent the same ASN.1 *OBJECT* *IDENTIFIER*. Any names and NIDs contained in the two objects are ignored, even if they differ between both objects. **OBJ\_dup**() returns a deep copy of the given *object* if it is marked as dynamically allocated. The new object and all data contained in it are marked as dynamically allocated. If the given *object* is not marked as dynamically allocated, **OBJ\_dup**() just returns a pointer to the *object* itself. ## RETURN VALUES Application code should treat all returned values — objects, names, and NIDs — as constants. **OBJ\_nid2obj**() returns a pointer to a table object owned by the library or NULL if no matching table object is found. **OBJ\_nid2ln**() and **OBJ\_nid2sn**() return a pointer to a string owned by a table object or NULL if no matching table object is found. For NID\_undef, they return the constant static strings "undefined" and "UNDEF", respectively. **OBJ\_obj2nid**() returns an NID on success, or NID\_undef if *object* is NULL, does not contain an OID, if no table object matching the OID is found, or if the matching object does not contain an NID. **OBJ\_ln2nid**() and **OBJ\_sn2nid**() return an NID on success or NID\_undef if no matching table object is found or if the matching object does not contain an NID. **OBJ\_txt2nid**() returns an NID on success or NID\_undef if parsing of *s* or memory allocation fails, if no matching table object is found, or if the matching object does not contain an NID. **OBJ\_txt2obj**() returns a pointer to a table object owned by the library if lookup of *s* as a long or short name succeeds. Otherwise, it returns a newly created object, transferring ownership to the caller, or NULL if parsing of *s* or memory allocation fails. **OBJ\_obj2txt**() and **i2t\_ASN1\_OBJECT**() return the amount of space required in bytes, including the terminating NUL byte, or zero if an error occurs before the required space can be calculated, in particular if *buf\_len* is negative, *object* is NULL or does not contain an OID, or if memory allocation fails. **OBJ\_cmp**() returns 0 if both objects refer to the same OID or neither of them are associated with any OID, or a non-zero value if at least one of them refers to an OID but the other one does not refer to the same OID. **OBJ\_dup**() returns the pointer to the original *object* if it is not marked as dynamically allocated. Otherwise, it returns a newly created object, transferring ownership to the caller, or NULL if *object* is NULL or memory allocation fails. **i2a\_ASN1\_OBJECT**() returns the number of bytes written, even if the given *object* is invalid or contains invalid data, but a negative value if memory allocation or a write operation fails. In some cases of failure of **OBJ\_nid2obj**(), **OBJ\_nid2ln**(), **OBJ\_nid2sn**(), **OBJ\_txt2nid**(), **OBJ\_txt2obj**(), **OBJ\_obj2txt**(), **OBJ\_dup**(), **i2t\_ASN1\_OBJECT**(), and **i2a\_ASN1\_OBJECT**(), the reason can be determined with ERR\_get\_error(3). ## EXAMPLES Retrieve the object for **commonName**: ``` ASN1_OBJECT *object; object = OBJ_nid2obj(NID_commonName); ``` Check whether an object contains the OID for **commonName**: ``` if (OBJ_obj2nid(object) == NID_commonName) /* Do something */ ``` Create a new object directly: ``` object = OBJ_txt2obj("1.2.3.4", 1); ``` ## SEE ALSO ASN1\_OBJECT\_new(3), BIO\_new(3), d2i\_ASN1\_OBJECT(3), OBJ\_create(3) ## HISTORY **OBJ\_nid2obj**(), **OBJ\_nid2ln**(), **OBJ\_nid2sn**(), **OBJ\_obj2nid**(), **OBJ\_ln2nid**(), **OBJ\_sn2nid**(), **OBJ\_txt2nid**(), **OBJ\_cmp**(), and **OBJ\_dup**() first appeared in SSLeay 0.5.1. **i2a\_ASN1\_OBJECT**() first appeared in SSLeay 0.6.0, and **i2t\_ASN1\_OBJECT**() in SSLeay 0.9.0. All these functions have been available since OpenBSD 2.4. **OBJ\_txt2obj**() first appeared in OpenSSL 0.9.2b. **OBJ\_obj2txt**() first appeared in OpenSSL 0.9.4. Both functions have been available since OpenBSD 2.6. ## CAVEATS The API contract of **OBJ\_txt2obj**() when called with a *no\_name* argument of 0 and of **OBJ\_dup**() is scary in so far as the caller cannot find out from the returned object whether it is owned by the library or whether ownership was transferred to the caller. Consequently, it is best practice to assume that ownership of the object may have been transferred and call ASN1\_OBJECT\_free(3) on the returned object when the caller no longer needs it. In case the library retained ownership of the returned object, ASN1\_OBJECT\_free(3) has no effect and is harmless. Objects returned from **OBJ\_txt2obj**() with a *no\_name* argument of 1 always require ASN1\_OBJECT\_free(3) to prevent memory leaks. Objects returned from **OBJ\_nid2obj**() never require ASN1\_OBJECT\_free(3), but calling it anyway has no effect and is harmless. ## BUGS Usually, an object is expected to contain an NID other than NID\_undef if and only if it is a table object. However, this is not an invariant guaranteed by the API. In particular, ASN1\_OBJECT\_create(3) allows the creation of non-table objects containing bogus NIDs. **OBJ\_obj2nid**() returns such bogus NIDs even though **OBJ\_nid2obj**() cannot use them for retrieval. On top of that, the global table contains one built-in object with an NID of NID\_undef. **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.