X509_NAME_GET_INDEX_BY_NID(3ossl)

✨ X509_NAME_GET_INDEX_BY_NID(3ossl) ✨

okay bestie, gather round 🫶 this is the OpenSSL page for the X509_NAME lookup + enumeration girlies, and yes it's a whole vibe. it's giving "I need to poke around inside a certificate name and find stuff."

---

🌸 NAME 🌸

X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry, X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ — the X509_NAME lookup and enumeration functions 💅

---

🌈 SYNOPSIS 🌈

#include <openssl/x509.h>

int X509_NAME_get_index_by_NID(const X509_NAME *name, int nid, int lastpos);
int X509_NAME_get_index_by_OBJ(const X509_NAME *name,
                               const ASN1_OBJECT *obj, int lastpos);

int X509_NAME_entry_count(const X509_NAME *name);
X509_NAME_ENTRY *X509_NAME_get_entry(const X509_NAME *name, int loc);

int X509_NAME_get_text_by_NID(const X509_NAME *name, int nid,
                              char *buf, int len);
int X509_NAME_get_text_by_OBJ(const X509_NAME *name, const ASN1_OBJECT *obj,
                              char *buf, int len);

---

💖 DESCRIPTION 💖

so these functions let you examine an X509_NAME structure. and like, an X509_NAME is literally the same thing as the Name type defined in RFC2459 (and honestly elsewhere too), and it's the thing used for certificate subject names and issuer names. main character of cert identity, no cap 👑

X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() go find the next index that matches nid or obj, starting after lastpos. so lastpos should be set to -1 at the very beginning, bestie. if there are no more entries, you get -1 back. and if nid is invalid (aka it doesn't correspond to a valid OID), you get -2 back. rude but okay 🙈

X509_NAME_entry_count() returns the total number of entries in name. it's the headcount. the attendance sheet. 📋

X509_NAME_get_entry() grabs the X509_NAME_ENTRY from name that corresponds to index loc. acceptable values for loc run from 0 to (X509_NAME_entry_count(name) - 1). and heads up — the value you get back is an internal pointer which must not be freed. do NOT free it. not yours. hands off. 🙅

X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() grab the "text" from the first entry in name that matches nid or obj. if no such entry exists, -1 comes back. at most len bytes get written, and the text written to buf will be null terminated. the length of the output string written is what gets returned, excluding the terminating null. and if buf is NULL, then you get back the amount of space needed in buf (again excluding the final null). love a little two-for-one 🫶

---

🦋 NOTES 🦋

okay so, real talk: X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() should be considered deprecated 💀 because they have various limitations that make them of, like, minimal use in practice. they can only find the first matching entry, and they'll copy the contents of the field verbatim. which is highly confusing if the target is a multicharacter string type like a BMPString or a UTF8String. it's giving chaos, honestly.

for a more general solution, you wanna use X509_NAME_get_index_by_NID() or X509_NAME_get_index_by_OBJ(), then X509_NAME_get_entry() on any matching indices, and then the various X509_NAME_ENTRY utility functions on the result. that's the glow-up path ✨

the list of all relevant NID_* and OBJ_* codes can be found in the source code header files <openssl/obj_mac.h> and/or <openssl/objects.h>. go read them, they're right there 📚

applications that could pass invalid NIDs to X509_NAME_get_index_by_NID() should check for the return value of -2. alternatively, the NID validity can be determined first by checking that OBJ_nid2obj(nid) is not NULL. your call, but pls check 🙏

---

👑 RETURN VALUES 👑

X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() return the index of the next matching entry, or -1 if it's not found. X509_NAME_get_index_by_NID() can also return -2 if the supplied NID is invalid. two flavors of "no" 💀

X509_NAME_entry_count() returns the total number of entries, and 0 for failure.

X509_NAME_get_entry() returns an X509_NAME pointer to the requested entry, or NULL if the index is invalid.

---

🎀 EXAMPLES 🎀

process all the entries, like a boss:

int i;
X509_NAME_ENTRY *e;

for (i = 0; i < X509_NAME_entry_count(nm); i++) {
    e = X509_NAME_get_entry(nm, i);
    /* Do something with e */
}

process all commonName entries, which is lowkey the useful one:

int lastpos = -1;
X509_NAME_ENTRY *e;

for (;;) {
    lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos);
    if (lastpos == -1)
        break;
    e = X509_NAME_get_entry(nm, lastpos);
    /* Do something with e */
}

---

🌟 SEE ALSO 🌟

ERR_get_error(3), d2i_X509_NAME(3)

---

💜 COPYRIGHT 💜

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, bestie 🫶 this was OpenSSL 3.5.9, dated 2026-09-29, filed under X509_NAME_GET_INDEX_BY_NID(3ossl). go forth and enumerate those names, you've got this 💅✨🌸