X509_STORE_NEW(3SSL)

💖 X509_STORE_NEW — the OpenSSL store allocation, freeing and locking fam 💖

okay bestie, sit down, we're talking about X509_STORE — that's the OpenSSL manual section 3 page for X509_STORE_new, X509_STORE_up_ref, X509_STORE_free, X509_STORE_lock and X509_STORE_unlock, aka the allocation, freeing and locking functions. it's giving ✨certificate store management✨ and honestly it's not even that deep once you know the vibe.

---

🌸 SYNOPSIS 🌸

#include <openssl/x509_vfy.h>

X509_STORE *X509_STORE_new(void);
void X509_STORE_free(X509_STORE *xs);
int X509_STORE_lock(X509_STORE *xs);
int X509_STORE_unlock(X509_STORE *xs);
int X509_STORE_up_ref(X509_STORE *xs);

that's it, that's the whole roster 🫶 yes there are five of them and yes they all live in <openssl/x509_vfy.h>, no cap.

---

✨ DESCRIPTION ✨

okay so like, here's the tea on each one:

• X509_STORE_new() — hands you a brand new X509_STORE. freshly birthed. iconic. 👑
• X509_STORE_up_ref() — bumps up the reference count that's hanging out with the X509_STORE object. more refs, more friends 💅
• X509_STORE_lock() — locks the store so other threads can't read from it or write to it. X509_STORE_unlock() does the opposite and sets it free 🦋. lowkey important: not every operation needs you to lock the store, so peek the thread-safety notes down below before you go lock-maxxing, bestie.
• X509_STORE_free() — decrements the reference count on the X509_STORE object. and the memory? it's only actually freed when that reference count hits zero — not a second before, main character energy 💀. and if the argument is NULL, literally nothing happens. NULL in, NULL out, we move on 🙈

---

📝 NOTES 📝

🧵 Thread Safety

when an X509_STORE is shared across multiple threads, every thread or component that's holding a pointer to it should call X509_STORE_up_ref() to acquire a reference, and then release that reference with X509_STORE_free() when it's done. no skipping steps. that's the whole contract ✨

adding certificates or CRLs — think X509_STORE_add_cert(3) or X509_STORE_add_crl(3) — and also looking up objects from the cache with X509_STORE_CTX_get_by_subject(3), are all safe to call concurrently from multiple threads on the same store without external synchronization, provided that ownership of the X509_STORE was obtained by acquiring a reference in advance. that proviso is doing a LOT of heavy lifting, so don't ignore her 🎀

⚠️ store configuration functions — X509_STORE_set_flags(), X509_STORE_set_depth(), X509_STORE_set_purpose(), X509_STORE_set_trust(), and similar — are NOT safe to call concurrently with any other operation on the same store. fr fr, do not do it. the store has to be fully configured before you share it with other threads. configure first, share later, that's the order 💅

one genuinely useful pattern: have a single owner thread that calls X509_STORE_free() only after joining with all the threads that use the store. one thread to rule the refcount, everyone else does their thing. slay 🫶

---

🎯 RETURN VALUES 🎯

• X509_STORE_new() — returns a shiny new X509_STORE, or NULL if the call fails 😭
• X509_STORE_up_ref(), X509_STORE_lock() and X509_STORE_unlock() — return 1 for success and 0 for failure. binary. no in-between. ⭐
• X509_STORE_free() — returns literally nothing. void. she gives nothing and takes nothing 🙈

---

👀 SEE ALSO 👀

X509_STORE_set_verify_cb_func(3) X509_STORE_get0_param(3)

go read those too, bestie, they're part of the saga 🌈

---

📜 HISTORY 📜

the X509_STORE_up_ref(), X509_STORE_lock() and X509_STORE_unlock() functions were added in OpenSSL 1.1.0. so if you're on something older than that, uh, good luck 💀

---

©️ COPYRIGHT ©️

Copyright 2016-2026 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 X509_STORE_NEW from OpenSSL, version 4.0.3, dated 2026-09-29. go lock responsibly and always free what you ref. mwah 💖✨