X509_NAME_ADD_ENTRY_BY_TXT(3ossl)

💖 X509_NAME_ADD_ENTRY_BY_TXT(3ossl) 💖

okay bestie, so this is the OpenSSL girlie manual, section 3ossl, and today we're talking about the X509_NAME modification functions. No cap, this is the glow-up your certificate names have been waiting for. ✨

---

🌸 NAME 🌸

X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID, X509_NAME_add_entry, X509_NAME_delete_entry — they're the X509_NAME modification functions, aka the ones that actually edit your name structures. 💅

---

✨ SYNOPSIS ✨

#include <openssl/x509.h>

int X509_NAME_add_entry_by_txt(X509_NAME *name, const char *field, int type,
                               const unsigned char *bytes, int len, int loc, int set);

int X509_NAME_add_entry_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int type,
                               const unsigned char *bytes, int len, int loc, int set);

int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type,
                               const unsigned char *bytes, int len, int loc, int set);

int X509_NAME_add_entry(X509_NAME *name, const X509_NAME_ENTRY *ne, int loc, int set);

X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc);

---

🦋 DESCRIPTION 🦋

so X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ() and X509_NAME_add_entry_by_NID() all add a field, but they figure out which field differently — one by a string field, one by an object obj, and one by a NID nid, respectively. The actual field value you're adding lives in bytes and has length len. And if len is -1? bestie, the field length gets calculated internally with strlen(bytes). 💖

The type of field is decided by type, and type can be either a definition of the type of bytes (think MBSTRING_ASC) or a standard ASN1 type (think V_ASN1_IA5STRING). Where does your new entry land? That's loc and set's job. 🎀

X509_NAME_add_entry() adds a copy of the X509_NAME_ENTRY structure ne to name. Position? Again, loc and set. And because it's a copy of ne that gets added, you still have to free ne yourself after the call. 😭 don't leak, queen.

X509_NAME_delete_entry() deletes an entry from name at position loc. The deleted entry gets returned to you and — say it with me — must be freed up. 🫶

---

🌈 NOTES 🌈

ngl, using string types like MBSTRING_ASC or MBSTRING_UTF8 for the type parameter is strongly recommended. Why? Because it lets the internal code correctly figure out the type of the field and apply length checks according to the relevant standards. That's literally done using ASN1_STRING_set_by_NID(). iconic.

But if you use an ASN1 type instead, no checks are performed and the supplied data in bytes is used directly. raw. unhinged. 💀

In X509_NAME_add_entry_by_txt(), the field string represents the field name using OBJ_txt2obj(field, 0).

Now, the loc and set parameters decide where a new entry gets added. For almost all applications you can set loc to -1 and set to 0. That adds a new entry to the end of name as a single valued RelativeDistinguishedName (RDN). easy. slay. ✨

loc is literally the index where the new entry is inserted: if it's -1, it's appended.

set determines how the new type is added. If it's zero, a new RDN is created.

If set is -1 or 1, it gets added as a new set member to the previous or next RDN structure, respectively. That then becomes part of a multi-valued RDN (containing a set of AVAs). And since multi-valued RDNs are very rarely used, set typically will be zero. periodt.

---

👑 RETURN VALUES 👑

X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(), X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for success, or 0 if an error occurred. 🎀

X509_NAME_delete_entry() returns either the deleted X509_NAME_ENTRY structure or NULL if an error occurred. 🙈

---

🍓 EXAMPLES 🍓

Create an X509_NAME structure:

"C=UK, O=Disorganized Organization, CN=Joe Bloggs"

X509_NAME *nm;

nm = X509_NAME_new();
if (nm == NULL)
    /* Some error */
if (!X509_NAME_add_entry_by_txt(nm, "C", MBSTRING_ASC,
                                "UK", -1, -1, 0))
    /* Error */
if (!X509_NAME_add_entry_by_txt(nm, "O", MBSTRING_ASC,
                                "Disorganized Organization", -1, -1, 0))
    /* Error */
if (!X509_NAME_add_entry_by_txt(nm, "CN", MBSTRING_ASC,
                                "Joe Bloggs", -1, -1, 0))
    /* Error */

---

💀 BUGS 💀

okay so type can still be set to V_ASN1_APP_CHOOSE to use a different algorithm to determine field types. And bestie… since this form doesn't understand multicharacter types, performs no length checks, and can result in invalid field types, its use is strongly discouraged. not the vibe. 🚫

fr fr, just don't. use the string types. your future self will thank you. 💜

---

🔥 SEE ALSO 🔥

ERR_get_error(3), d2i_X509_NAME(3)

---

🧚 COPYRIGHT 🧚

Copyright 2002-2020 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, and honestly? she ate. go forth and modify your X509_NAMEs responsibly, mwah 💅✨🌸