SSL_SESSION_FREE(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💖 SSL_SESSION_FREE 💖 — like, the whole SSL_SESSION lifecycle, bestie

okay so this is the manual page for the SSL_SESSION family in OpenSSL (that's the 3SSL section, iykyk). We're talking SSL_SESSION_new, SSL_SESSION_dup, SSL_SESSION_up_ref, and SSL_SESSION_free — creating, freeing, and managing SSL_SESSION structures. Refcount management, periodt. 🎀

✨ SYNOPSIS ✨

#include <openssl/ssl.h>

SSL_SESSION *SSL_SESSION_new(void);
SSL_SESSION *SSL_SESSION_dup(const SSL_SESSION *src);
int SSL_SESSION_up_ref(SSL_SESSION *ses);
void SSL_SESSION_free(SSL_SESSION *session);

🌸 DESCRIPTION 🌸

  • SSL_SESSION_new() — makes a brand new SSL_SESSION structure and hands you back a pointer to it. Fresh out the box, no notes. ✨
  • SSL_SESSION_dup() — makes a new SSL_SESSION structure that is a copy of src. Lowkey important detail: the copy is not owned by any cache that src may have been in. So it's a free agent, okay?
  • SSL_SESSION_up_ref() — bumps the reference count on the SSL_SESSION structure you pass in. Glow up for the refcount, fr fr. 🫶
  • SSL_SESSION_free() — decrements the reference count of session, and if that count has hit 0, it removes the SSL_SESSION structure pointed to by session and frees up the allocated memory. And if session is NULL? Nothing happens. Nothing. Zero. Nada. 💀

👑 NOTES 👑

okay so here's the lore. 🦋

SSL_SESSION objects get allocated when a TLS/SSL handshake operation is successfully completed. Depending on the settings — go check SSL_CTX_set_session_cache_mode(3) for that — the SSL_SESSION objects are internally referenced by the SSL_CTX and linked into its session cache.

And here's the plot twist: SSL objects may be using the SSL_SESSION object. Because a session may be reused, several SSL objects may be using one SSL_SESSION object at the same time. The way that multiple things can point at the same little guy... iconic but also terrifying. 😭

So it is crucial to keep the reference count (that's the usage information) correct, and to not delete an SSL_SESSION object that is still being used — because that may lead to program failures due to dangling pointers. And the messiest part? These failures may also appear delayed. Like, for example, when an SSL_SESSION object was completely freed because the reference count incorrectly became 0, but it is still referenced in the internal session cache and the cache list gets processed during a SSL_CTX_flush_sessions(3) operation. So it's giving time-bomb energy. 🕰️💥

🚨 bestie listen: 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(), 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. Do not freestyle this one. 🙈

⭐ RETURN VALUES ⭐

  • SSL_SESSION_new returns a pointer to the newly allocated SSL_SESSION structure, or NULL on error.
  • SSL_SESSION_dup returns a pointer to the new copy, or NULL on error.
  • SSL_SESSION_up_ref returns 1 on success or 0 on error.

🌈 SEE ALSO 🌈

ssl(7), SSL_get_session(3), SSL_CTX_set_session_cache_mode(3), SSL_CTX_flush_sessions(3), d2i_SSL_SESSION(3)

Go read those too, bestie, they're all connected. It's giving unhinged extended universe. 💅

💜 HISTORY 💜

The SSL_SESSION_dup() function was added in OpenSSL 1.1.1.

Copyright 2000-2023 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, no cap. 🍓 this was OpenSSL 4.0.3, dated 2026-09-29, straight from the 3SSL manual set — love that for us, mwah 💖✨

📦 where this page comes from