OBJ_NID2OBJ(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

✨ NAME ✨

okay bestie, gather round, because this page is the whole ASN1 object friend group: i2t_ASN1_OBJECT, OBJ_length, OBJ_get0_data, OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup, OBJ_add_sigid — aka the ASN1 object utility functions. 💖

🌸 SYNOPSIS 🌸

first thing, you gotta invite the header file in:

#include <openssl/objects.h>

then the squad rolls up like this:

ASN1_OBJECT *OBJ_nid2obj(int n);
const char *OBJ_nid2ln(int n);
const char *OBJ_nid2sn(int n);

int OBJ_obj2nid(const ASN1_OBJECT *o);
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 *a, int no_name);

int i2t_ASN1_OBJECT(char *buf, int buf_len, const ASN1_OBJECT *a);

int OBJ_cmp(const ASN1_OBJECT *a, const ASN1_OBJECT *b);
ASN1_OBJECT *OBJ_dup(const ASN1_OBJECT *o);

int OBJ_create(const char *oid, const char *sn, const char *ln);

size_t OBJ_length(const ASN1_OBJECT *obj);
const unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj);

int OBJ_add_sigid(int signid, int dig_id, int pkey_id);

and now the one that's lowkey cancelled 👇 this next function has been deprecated since OpenSSL 1.1.0, and you can hide it entirely by defining OPENSSL_API_COMPAT with a suitable version value — see openssl_user_macros(7):

void OBJ_cleanup(void);

💖 DESCRIPTION 💖

so the ASN1 object utility functions are the ones that handle ASN1_OBJECT structures, which are basically the glow-up of the ASN1 OBJECT IDENTIFIER (OID) type. For convenience, OIDs usually show up in source code as numeric identifiers, aka NIDs. OpenSSL keeps an internal table of OIDs that gets generated when the library is built, and their matching NIDs are sitting right there as defined constants. For all the functions below, application code should treat every returned value — OIDs, NIDs or names — as constants. no take-backs, no editing. 🫶

  • OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() — these three take the NID n and convert it into an ASN1_OBJECT structure, its long name, and its short name respectively. If something went wrong, you get NULL. 😭
  • OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() — the reverse trip: they return the matching NID for the object o, the long name ln, or the short name sn respectively, or NID_undef if an error happened.
  • OBJ_txt2nid() — returns the NID that corresponds to the text string s. and s is flexible bestie, it can be a long name, a short name, or the numerical representation of an object. ✨
  • OBJ_txt2obj() — converts the text string s into an ASN1_OBJECT structure. If no_name is 0, then long names and short names get interpreted as well as the numerical forms. If no_name is 1, only the numerical form is acceptable. periodt.
  • OBJ_obj2txt() — converts the ASN1_OBJECT a into a textual representation. Unless buf is NULL, that representation gets written as a NUL-terminated string to buf, where at most buf_len bytes are written, truncating the result if necessary. Either way it returns the total string length, excluding the NUL character, that's required for the non-truncated representation — or -1 on error. If no_name is 0, then if the object has a long or short name that one gets used, otherwise the numerical form is used. If no_name is 1, the numerical form is always used. no exceptions, she's committed. 💅
  • i2t_ASN1_OBJECT() — literally just OBJ_obj2txt() with no_name set to zero. same energy, less typing.
  • OBJ_cmp() — compares a to b. If the two are identical, 0 is returned. 💀
  • OBJ_dup() — hands you a copy of o. iconic behaviour.
  • OBJ_create() — adds a new object to the internal table. oid is the numerical form of the object, sn is the short name and ln is the long name. On success you get a new NID for the created object back; on failure you get NID_undef. Any of oid, sn and ln may be NULL, but not all at once — pick at least one, bestie, we're not doing that today. 🍓
  • OBJ_length() — returns the size of the content octets of obj.
  • OBJ_get0_data() — returns a pointer to the content octets of obj. careful though: the returned pointer is an internal pointer which must not be freed. do NOT free it. I'm serious. 🚨
  • OBJ_add_sigid() — creates a new composite "Signature Algorithm" that associates a given NID with two other NIDs: one representing the underlying signature algorithm, and the other representing a digest algorithm to be used in conjunction with it. signid is the NID for the composite "Signature Algorithm", dig_id is the NID for the digest algorithm, and pkey_id is the NID for the underlying signature algorithm. And because some signature algorithms don't need a digest at all, NID_undef is a totally valid dig_id. slay. 🌈
  • OBJ_cleanup() — releases any resources allocated by creating new objects.

🎀 NOTES 🎀

Objects in OpenSSL can have a short name, a long name and a numerical identifier (NID) attached to them. A standard set of objects lives in an internal table, and the appropriate values are defined in the header file objects.h. 📚

for example, the OID for commonName has these 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: their NIDs can be used in a C language switch statement, for example. They're also static constant structures which are shared — meaning there is only a single constant structure for each table object. main character energy, honestly. 👑

Objects which are not in the table have the NID value NID_undef. 😬

Good news: objects do not need to be in the internal tables to be processed — OBJ_txt2obj() and OBJ_obj2txt() can handle the numerical form of an OID all on their own. 💪

Some objects are used to represent algorithms which don't have a corresponding ASN.1 OBJECT IDENTIFIER encoding (for example, no OID currently exists for a particular algorithm). Because of that, they can't be encoded or decoded as part of ASN.1 structures. Applications can figure out whether there's a corresponding OBJECT IDENTIFIER by checking that 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 can't be constant because it needs to be freed after use. the duality of OID. 🦋

⚠️ heads up: these functions were not thread safe in OpenSSL 3.0 and before. fr fr, keep that in mind.

🦋 RETURN VALUES 🦋

  • OBJ_nid2obj() — returns an ASN1_OBJECT structure, or NULL if an error occurred.
  • OBJ_nid2ln() and OBJ_nid2sn() — return a valid string, or NULL on error.
  • OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() — return a NID, or NID_undef on error.
  • OBJ_add_sigid() — returns 1 on success or 0 on error.
  • i2t_ASN1_OBJECT() and OBJ_obj2txt() — return -1 on error. On success, they return the length of the string written to buf if buf is not NULL and buf_len is big enough, otherwise the total string length. and note: this does not count the trailing NUL character. no cap. 💅

⭐ EXAMPLES ⭐

Create an object for commonName:

ASN1_OBJECT *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 = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
ASN1_OBJECT *obj = OBJ_nid2obj(new_nid);

Create a new object directly:

obj = OBJ_txt2obj("1.2.3.4", 1);

👑 SEE ALSO 👑

go read ERR_get_error(3) next, bestie. it's giving required reading. 🫶

🌈 HISTORY 🌈

OBJ_cleanup() was deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto(3) and should not be used. she's retired, let her rest. 😭

Copyright 2002-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (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>.

and that's the whole page, babe 💖 this was OpenSSL 4.0.3, dated 2026-09-29, filed under OBJ_NID2OBJ(3SSL). ily, go convert some OIDs. 🎀✨🦋

📦 where this page comes from