X509_NEW(3ossl)

💖 X509_NEW(3ossl) — the certificate alloc/free page, bestie edition 💖

Okay so real quick, the manual name for this one is X509_NEW(3ossl) — that's the OpenSSL page you're on, and it's literally all about the alloc/free squad for X509 certificate ASN1 stuff. Let's go 🎀

✨ NAME ✨

X509_new, X509_new_ex, X509_free, X509_up_ref, X509_chain_up_ref, OSSL_STACK_OF_X509_free — these are the X509 certificate ASN1 allocation and deallocation functions. Basically the birth and death (and refcount glow-up) of your cert objects, no cap 💅

🌸 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 🦋

The X509 ASN1 allocation routines allocate and free an X509 structure, which represents an X509 certificate. That's the whole vibe 🫶

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. And listen — a bunch of X509 functions like X509_check_purpose() and X509_verify() use this library context to pick which providers supply the fetched algorithms (SHA1 is used internally, iykyk). This created X509 object can then be used when loading binary data using d2i_X509(). Iconic behavior tbh ⭐

X509_new() is similar to X509_new_ex() but sets the library context and property query to NULL. Which means the default (NULL) library context gets used for any X509 operations that require algorithm fetches. Lowkey the chill version 😌

X509_free() decrements the reference count of the X509 structure a and frees it up if the reference count is zero. If the argument is NULL, nothing is done — it literally just minds its own business 🙈

X509_up_ref() increments the reference count of a. Glow-up secured ✨

X509_chain_up_ref() increases the reference count of all certificates in chain x and returns a copy of the stack, or an empty stack if a is NULL. (Yes, that arg is spelled a right there in the source, we don't make the rules 💀)

OSSL_STACK_OF_X509_free() deallocates the given list of pointers to certificates after calling X509_free() on all its elements. If the argument is NULL, nothing is done. Cleanup crew, main character energy 🧹👑

---

💜 NOTES 💜

The function X509_up_ref() is useful if a certificate structure is being used by several different operations, each of which will free it up after use — this avoids the need to duplicate the entire certificate structure. Sharing is caring, and copying is expensive, fr fr 💸

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() — but it serves a similar purpose: the returned chain persists after the original has been freed. So like, your chain outlives the drama 🦋

Heads up bestie, X509_up_ref() is spelled with a "useful" in the original text (if useful if) — we're keeping the facts exactly as they are, typo and all 💅

🔥 RETURN VALUES 🔥

• If the allocation fails, X509_new() returns NULL and sets an error code that can be obtained by ERR_get_error(3). Otherwise it returns 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 gives nothing back, and honestly? Respect 😭

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

Go read them. All of them. Obsessed 🫶

⭐ HISTORY ⭐

X509_new_ex() was added in OpenSSL 3.0.

OSSL_STACK_OF_X509_free() was added in OpenSSL 3.2.

Newer than your fave, periodt 💅

🍓 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>.

---

And that's the whole page, bestie 💖 This was the X509_NEW(3ossl) manual, OpenSSL 3.5.6, dated 2026-04-07 — screenshot it, cite it, live by it. Slay 🎀✨