ASN1_ITEM_NEW(3)

💅 ASN1_ITEM_NEW(3) — generic ASN.1 value constructor and destructor

okay so this is a page from the Library Functions Manual (section 3, the library-call girlies ✨), and it's literally about making and unmaking ASN.1 values with two little functions. bestie, buckle up 🎀

---

✨ NAME ✨

ASN1_item_new, ASN1_item_free — the generic ASN.1 value constructor and destructor. one builds the thing, one yeets it into the void. iconic duo behavior, honestly 🫶

---

🌸 SYNOPSIS 🌸

#include <openssl/asn1.h>

ASN1_VALUE *
ASN1_item_new(const ASN1_ITEM *it);

void
ASN1_item_free(ASN1_VALUE *val_in, const ASN1_ITEM *it);

like, that's it. two lines of code and your whole ASN.1 life is handled 💅

---

💖 DESCRIPTION 💖

ASN1_item_new() allocates and initializes a fresh empty ASN.1 value — and the type of that value is described by the global static object it. so it is basically the blueprint, the vibe check, the whole personality of the thing you're about to make 🦋

Now for the destructor side of things. If the item type described by it is reference counted, ASN1_item_free() decrements the reference count of val_in. Otherwise — or if the reference count actually reaches 0 — ASN1_item_free() frees val_in, and it just assumes it's of the type described by it.

that assumption is doing a LOT of heavy lifting, bestie. If the true type of val_in fails to match the it you gave it, buffer overflows and segmentation faults are likely to occur. 😭 and here's the gut punch: it is not possible to recover the type of an ASN1_VALUE object by inspecting it. the type always needs to be remembered separately. no take-backs, no detective work, no scrolling up in the group chat to figure out what it was. you just have to know. 💀

ASN1_VALUE is an incomplete type, which means pointers to it always require casting to the correct complete type before they can be dereferenced. for all practical purposes, a pointer to ASN1_VALUE is equivalent to a void pointer. it's giving "I know a guy but I can't tell you what he does" energy 🙈

Depending on it, there are more than 150 different types that ASN1_item_new() may return. most of them are pointers to structures or pointers to arrays of structures — but there are a few exceptions, and they are so worth calling out:

• If it is ASN1_NULL_it, ASN1_item_new() returns a specific invalid pointer representing the unique ASN1_NULL object. ✨ not me getting an invalid pointer on purpose
• If it's LONG_it, ASN1_item_new() does not return a pointer at all, but a long value cast to ASN1_VALUE *. it's not even a pointer, it's a long in a pointer costume 🎭

---

⭐ RETURN VALUES ⭐

The ASN1_item_new() function returns the new ASN1_VALUE object if successful. slay. otherwise NULL is returned, and you can go retrieve an error code with ERR_get_error(3). it's giving "the call is coming from inside the error queue" 🔥

---

🦋 SEE ALSO 🦋

ASN1_get_object(3), ASN1_item_d2i(3), ASN1_item_digest(3), ASN1_item_pack(3), ASN1_item_sign(3), ASN1_item_verify(3), ASN1_NULL_new(3), ASN1_TYPE_new(3), d2i_ASN1_NULL(3), OBJ_nid2obj(3)

the whole friend group, fr fr. go read them, they're all lowkey relevant 👑

---

👑 HISTORY 👑

ASN1_item_new() and ASN1_item_free() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2. vintage. retro. they've been doing this since before you were born 💜

---

💀 BUGS 💀

The ASN1_VALUE type compromises type safety and invites programming mistakes that will typically have severe consequences.

no cap, this is the "we don't do type safety here" warning and you should take it personally. type safety is not a vibe, it's a requirement. 🙏

---

and that's the page!! go forth and construct responsibly, bestie 🌈

cute little sign-off: this was the Debian edition of the page, dated January 12, 2022 — mwah, and remember: always keep track of your it 🎀