X509_NEW(3ossl)

📦
version 3.5.9 · 8 versions
, in fedora 43, fedora 44

💖 X509_NEW — bestie edition 💖

okay so this is X509_NEW(3ossl), a page from the OpenSSL manual, and it's all about the allocation + deallocation glow-up for X509 certificates. sit with me, we're gonna get through this together 🫶

✨ NAME ✨

X509_new, X509_new_ex, X509_free, X509_up_ref, X509_chain_up_ref, OSSL_STACK_OF_X509_free — the X509 certificate ASN1 allocation and deallocation functions. yes bestie, this is the birth-and-death page for certificate objects 👑

🌸 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, which is literally the representation of 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 the way that matters is: lots 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 freshly created X509 object can then be used when you're loading binary data with d2i_X509(). slay ✨

X509_new() is the same energy as X509_new_ex() except it sets the library context and property query to NULL. which means the default (NULL) library context gets used for any X509 operations that need algorithm fetches. no cap.

X509_free() decrements the reference count of the X509 structure a and frees it up if that reference count is zero. and if the argument is NULL? bestie, nothing happens. we simply do not engage 🙈

X509_up_ref() increments the reference count of a. that's it, that's the function 💖

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 its elements. and if the argument is NULL, nothing is done. iconic behavior tbh.

🎀 NOTES 🎀

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. it's giving sharing-is-caring, but make it memory-safe 🧚

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

⭐ 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 returns a pointer to the newly allocated structure. it's giving all-or-nothing 😭
  • 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 void, bestie, it simply does not report back 💀

🌈 SEE ALSO 🌈

💜 HISTORY 💜

  • X509_new_ex() was added in OpenSSL 3.0.
  • OSSL_STACK_OF_X509_free() was added in OpenSSL 3.2.

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

okay that's the whole page, no notes, no skips, every flag and every caveat is right there 💖

and that's a wrap bestie!! this page is OpenSSL 3.5.9, dated 2026-09-29, and it lives at X509_NEW(3ossl). go forth and manage your reference counts responsibly, mwah 🎀✨💅

📦 where this page comes from