X509_NEW(3SSL)

💖 X509_NEW 💖 (that's the 3SSL manual, bestie)

okay so real talk, this is the page about allocating and deallocating X509 certificate structures — X509_new, X509_new_ex, X509_free, X509_up_ref, X509_chain_up_ref, and OSSL_STACK_OF_X509_free. it's giving "certificate object lifecycle management" and honestly? iconic.

---

✨ NAME ✨

X509_new, X509_new_ex, X509_free, X509_up_ref, X509_chain_up_ref, OSSL_STACK_OF_X509_free — X509 certificate ASN1 allocation and deallocation functions 🎀

---

🌸 SYNOPSIS 🌸

#include <openssl/x509.h>

X509 *X509_new(void);
X509 *X509_new_ex(OSSL_LIB_CTX *libctx, const char *propq);
void X509_free(X509 *a);
int X509_up_ref(X509 *a);
STACK_OF(X509) *X509_chain_up_ref(STACK_OF(X509) *x);
void OSSL_STACK_OF_X509_free(STACK_OF(X509) *certs);

---

🦋 DESCRIPTION 🦋

so the X509 ASN1 allocation routines allocate and free an X509 structure, and that structure is literally an X509 certificate, no big deal 💅

X509_new_ex() allocates and initializes an X509 structure with a library context of libctx, a property query of propq, and a reference count of 1. a whole bunch of X509 functions — like X509_check_purpose() and X509_verify() — use this library context to pick which providers supply the fetched algorithms (btw SHA1 is used internally, noted 📝). this freshly created X509 object can then be used when you're loading binary data with d2i_X509().

X509_new() is basically the same vibe as X509_new_ex() except it sets the library context and property query to NULL. so any X509 operation that needs to fetch an algorithm just ends up using the default (NULL) library context. simple as that.

X509_free() decrements the reference count of the X509 structure a and frees it up once that reference count hits zero 🎉 and if the argument is NULL? nothing happens. no stress, no crash, we love to see it.

X509_up_ref() increments the reference count of a.

X509_chain_up_ref() increases the reference count of all the certificates in chain x and returns a copy of the stack — or an empty stack if a is NULL.

OSSL_STACK_OF_X509_free() deallocates the given list of pointers to certificates, after calling X509_free() on all of its elements. and yup, if the argument is NULL, nothing is done. 🫶

---

👑 NOTES 👑

the function X509_up_ref() is useful if a certificate structure is being used by several different operations and every single one of them will free it up after use: this saves you from having to duplicate the entire certificate structure. the way that's efficient 😌

the function X509_chain_up_ref() doesn't just up the reference count of each certificate. it also returns a copy of the stack, using sk_X509_dup(). different mechanics, same energy though — the purpose is similar: the returned chain persists even after the original has been freed. lowkey genius.

---

💀 RETURN VALUES 💀

if the allocation fails, X509_new() returns NULL and sets an error code that you can grab with ERR_get_error(3). otherwise it hands you a pointer to the newly allocated structure. ✨

X509_up_ref() returns 1 for success and 0 for failure.

X509_chain_up_ref() returns a copy of the stack, or NULL if an error occurred.

OSSL_STACK_OF_X509_free() has no return value. it's a void girlie, she gives nothing back and that's fine 💅

---

🌈 SEE ALSO 🌈

d2i_X509(3), ERR_get_error(3), X509_CRL_get0_by_serial(3), X509_get0_signature(3), X509_get_ext_d2i(3), X509_get_extension_flags(3), X509_get_pubkey(3), X509_get_subject_name(3), X509_get_version(3), X509_NAME_add_entry_by_txt(3), X509_NAME_ENTRY_get_object(3), X509_NAME_get_index_by_NID(3), X509_NAME_print_ex(3), X509_sign(3), X509V3_get_d2i(3), X509_verify_cert(3)

---

⭐ HISTORY ⭐

X509_new_ex() was added in OpenSSL 3.0.

OSSL_STACK_OF_X509_free() was added in OpenSSL 3.2.

---

🎀 COPYRIGHT 🎀

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

---

ok bestie that's the whole page, every flag, every return value, every reference, not a single detail skipped, no cap 💖

and that's a wrap on OpenSSL 4.0.3, dated 2026-09-29 — X509_NEW(3SSL), signing off 🦋✨💜