SSL_SESSION_FREE(3)

okay so bestie, you've landed on SSL_SESSION_FREE(3) from the Library Functions Manual, and it's literally the reference-counting saga for SSL_SESSION 💅 no cap, this one matters.

---

💖 NAME 💖

SSL_SESSION_up_ref, SSL_SESSION_free — SSL_SESSION reference counting. that's the whole vibe: one function bumps the count up, the other brings it down. 🎀

🌸 SYNOPSIS 🌸

the header/library situation and signatures, exactly as they come:

library “libssl” libcrypto #include <openssl/ssl.h>

int
SSL_SESSION_up_ref(SSL_SESSION *session);

void
SSL_SESSION_free(SSL_SESSION *session);

🦋 DESCRIPTION 🦋

okay so SSL_SESSION_up_ref() increments the reference count of the given session by 1. slay. it's giving "one more user is holding onto this thing" ✨

SSL_SESSION_free() decrements the reference count of the given session by 1. if the reference count reaches 0, it frees the memory used by the session. and if session is a NULL pointer, no action occurs — literally nothing happens, no notes. 💀

where do these SSL_SESSION objects come from? they're allocated when a TLS/SSL handshake operation is successfully completed. depending on the settings — see SSL_CTX_set_session_cache_mode(3) — the SSL_SESSION objects are internally referenced by the SSL_CTX and linked into its session cache. SSL objects may be using the SSL_SESSION object; as a session may be reused, several SSL objects may be using one SSL_SESSION object at the same time. iykyk, this is why the count has main character energy. 👑

bestie, this is the crucial part: keep the reference count (usage information) correct. do not delete a SSL_SESSION object that is still used, because that may lead to program failures due to dangling pointers. 😭

these failures may also appear delayed, e.g., when an SSL_SESSION object is completely freed as the reference count incorrectly becomes 0, but it is still referenced in the internal session cache and the cache list is processed during a SSL_CTX_flush_sessions(3) operation. so yeah, delayed chaos is still chaos. 🔥

SSL_SESSION_free() must only be called for SSL_SESSION objects for which the reference count was explicitly incremented (e.g., by calling SSL_get1_session(3); see SSL_get_session(3)) or when the SSL_SESSION object was generated outside a TLS handshake operation, e.g., by using d2i_SSL_SESSION(3).

it must not be called on other SSL_SESSION objects, as this would cause incorrect reference counts and therefore program failures. periodt. 🚫

👑 RETURN VALUES 👑

SSL_SESSION_up_ref() returns 1 on success or 0 on error. that's it. iconic binary reporting. ✅

🌈 SEE ALSO 🌈

• d2i_SSL_SESSION(3)
• ssl(3)
• SSL_CTX_flush_sessions(3)
• SSL_CTX_set_session_cache_mode(3)
• SSL_get_session(3)
• SSL_SESSION_new(3)

⭐ HISTORY ⭐

SSL_SESSION_free() first appeared in SSLeay 0.5.2 and has been available since OpenBSD 2.4. 🕰️

SSL_SESSION_up_ref() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 6.3. ✨

---

xoxo, this page is brought to you by Debian, dated June 8, 2025 — mwah 💋💖