OBJ_NID2OBJ(3)

💅 OBJ_NID2OBJ — inspect and create ASN.1 object identifiers ✨

okay so this is a libcrypto (OpenSSL) manual page, bestie — buckle up, it's giving "big API, big feelings" 🎀

---

🌸 SYNOPSIS 🌸

library “libcrypto”
#include <openssl/objects.h>

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 <openssl/asn1.h>

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 🦋

So these ASN.1 object utility functions process ASN1_OBJECT structures — and from here on we're just gonna call those "objects", mwah 💖. An object represents an ASN.1 OBJECT IDENTIFIER (OID). The library keeps an internal global table of objects, and a whole bunch of them are built into the library and just... live in that global table by default 👑. Your app can add more objects to the global table using the functions documented over in OBJ_create(3).

So yeah — three whole classes of objects, and yes the friend group has lore:

• built-in table objects 🌟
• user-defined table objects 🫶
• non-table objects 🙈

---

💜 the anatomy of an object

Besides the OID, each object can hold a long name, a short name, and a numerical identifier (NID). NGL the whole NID concept is specific to this library and is not standardized, but using the NID is often genuinely the most convenient way for source code to refer to a specific OID. And the NIDs of the built-in objects are available as defined constants, periodt ✨

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're also shared: there is only a single static constant structure for each built-in OID. iconic behaviour, honestly.

---

🎀 functions that only work on table objects

• OBJ_nid2obj() — retrieves the table object associated with the nid.
• OBJ_nid2ln() and OBJ_nid2sn() — retrieve its long name and short name, respectively. (yes, one for each, they're not gonna combine into one function for you 💅)
• OBJ_obj2nid() — retrieves the NID associated with the given object. That's 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. versatile queen 💅

---

🌈 functions that work on table objects AND non-table objects

The remaining functions are the chill ones — they work 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() — the same as OBJ_obj2txt() with no_name set to 0. basically the low-effort twin 😌
• 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. Let me spell out the drama:
  • 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 "<INVALID>". 💀
  • 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. it's giving "we're the same OID at our core" 🧚
• 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. no copy, no drama 🌸

---

⭐ RETURN VALUES ⭐

First things first, bestie: application code should treat all returned values — objects, names, and NIDs — as constants. don't be out here mutating them, ikykyk 🙈

• 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. cute little special case 💅
• 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. 👀 remember this one, it comes back in CAVEATS.
• 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.

And 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);

slay, you did it 🎉

---

🌟 SEE ALSO 🌟

ASN1_OBJECT_new(3), BIO_new(3), d2i_ASN1_OBJECT(3), OBJ_create(3)

go read those too, they're the supporting cast 🫶

---

👑 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. elders of the group chat, fr fr 🧓✨

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 💀

okay this is the part where we hold hands 🫶

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. like, hello?? 😭

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. so literally just call it, it's free real estate 💅

Objects returned from OBJ_txt2obj() with a no_name argument of 1 always require ASN1_OBJECT_free(3) to prevent memory leaks. no exceptions, bestie, that's how you leak 🚰

Objects returned from OBJ_nid2obj() never require ASN1_OBJECT_free(3), but calling it anyway has no effect and is harmless.

⚠️ tl;dr — when in doubt, call ASN1_OBJECT_free(3). worst case it's a no-op, best case you saved your process from a leak.

---

🐛 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. so yeah, chaos 💀

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. write that down 📝

---

and that's the whole page, bestie 💜 this version of the OBJ_NID2OBJ(3) manual shipped with Debian, dated June 8, 2025 — go forth and OID responsibly 🎀✨