X509_NAME_GET_INDEX_BY_NID(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

🎀 NAME 🎀

okay so bestie, say hi to the X509_NAME lookup-and-enumeration girlies 👑 — that's 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, and X509_NAME_get_text_by_OBJ.

and yes, this is the 3SSL manual page, aka the OpenSSL corner of the man-verse. iykyk 💅

✨ 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);
const X509_NAME_ENTRY *X509_NAME_get_entry(const X509_NAME *name, int loc);

Deprecated Functions:

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 💖

these functions let you poke around inside an X509_NAME structure 🔍. and fun fact: an X509_NAME is literally the same thing as the Name type defined in RFC 5280 (and elsewhere too, she gets around 💅) — you've seen her in certificate subject and issuer names, being all important and iconic.

X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() go grab you the next index that matches nid or obj after lastpos. bestie, you wanna start with lastpos set to -1, fr fr. if there are no more entries left, you get -1 back. and if the nid is invalid (like, it doesn't correspond to a valid OID at all 🙈), you get -2.

X509_NAME_entry_count() just tells you the total number of entries in name. that's it. she's the chill one 🧚

X509_NAME_get_entry() retrieves the X509_NAME_ENTRY from name that matches index loc. the acceptable range for loc runs from 0 to (X509_NAME_entry_count(name) - 1) — color inside the lines, babe. and heads up: what you get back is an internal pointer, so do not free it 🚫. it's not yours, it's hers.

X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() pull the "text" out of the first entry in name that matches nid or obj. if there's no such entry, you get -1. at most len bytes get written, and the text written to buf is null terminated ✍️. the return value is the length of the output string that got written — not counting that terminating null. and ooh, plot twist: if buf is NULL, then you get back the amount of space needed in buf instead (also not counting the final null). she's flexible like that ✨

🫶 NOTES 🫶

⚠️ okay so important tea: X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() have been deprecated since OpenSSL 4.0. not cancelled, but like... on notice 💀

they've got a bunch of limitations that make them of minimal use in practice. they can only find the first matching entry, and they'll copy the contents of the field verbatim — which can be highly confusing if your target is a multicharacter string type like a BMPString or a UTF8String. like, bestie, that's not the vibe at all 😭.

for a more general solution, use X509_NAME_get_index_by_NID() or X509_NAME_get_index_by_OBJ() first, then X509_NAME_get_entry() on any matching indices, and then the various X509_NAME_ENTRY utility functions on the result. that's the main-character path 👑

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

and if your app could possibly pass invalid NIDs to X509_NAME_get_index_by_NID()? you should be checking for that return value of -2 🕵️. alternatively you can determine NID validity ahead of time by checking that OBJ_nid2obj(nid) is not NULL. either way, vibe check your inputs 💅

⭐ 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 whole failure modes, she contains multitudes 🙈
  • 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 entries: 🦋

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: 🌈

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 🦋

go read those too, they're part of the friend group 🫶

Copyright 2002-2026 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>.

okay that's the whole page, bestie, you made it to the end 🎉 this was OpenSSL 4.0.3, dated 2026-09-29, filed under X509_NAME_GET_INDEX_BY_NID(3SSL) — now go forth and enumerate those name entries like the icon you are 💅✨🌸

📦 where this page comes from