SSL_CTX_SESS_SET_GET_CB(3)

🌸 SSL_CTX_SESS_SET_GET_CB(3) 🌸

okay so this is the SSL_CTX_SESS_SET_GET_CB(3) page, from the Library Functions Manual, and bestie it is literally all about callback functions for server side external session caching ✨ like that's the whole vibe 💅

---

💖 NAME 💖

SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb — these provide callback functions for server side external session caching 🫶

---

✨ SYNOPSIS ✨

so first of all, we're in libssl libcrypto land, and you gotta pull in the header:

#include <openssl/ssl.h>

then, the setters 🎀:

void
SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
    int (*new_session_cb)(SSL *, SSL_SESSION *));

void
SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
    void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *));

void
SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
    SSL_SESSION (*get_session_cb)(SSL *, const unsigned char *, int, int *));

and the getters, which are giving function-returning-a-function-pointer main character energy 👑:

int
(*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(SSL *ssl, SSL_SESSION *sess);

void
(*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(SSL_CTX *ctx,
    SSL_SESSION *sess);

SSL_SESSION *
(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(SSL *ssl,
    const unsigned char *data, int len, int *copy);

and then the callback prototypes themselves, spelled out all cute 🦋:

int
(*new_session_cb)(SSL *ssl, SSL_SESSION *sess);

void
(*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *sess);

SSL_SESSION *
(*get_session_cb)(SSL *ssl, unsigned char *data, int len, int *copy);

🚨 quick vibe check: in the set_get_cb version above, data is const unsigned char *, but in the standalone get_session_cb typedef it's just unsigned char *. that's how the page has it, so don't come for me, i'm just the messenger 😭

---

💅 DESCRIPTION 💅

the setters 🌸

• SSL_CTX_sess_set_new_cb() — sets the callback function that gets called automatically whenever a new session was negotiated. no cap, every single time 🔥
• SSL_CTX_sess_set_remove_cb() — sets the callback function that gets called automatically whenever a session is removed by the SSL engine. and why would the engine do that? because the session is considered faulty, or because it's become obsolete from exceeding the timeout value. expired = evicted, basically 💀
• SSL_CTX_sess_set_get_cb() — sets the callback function that gets called whenever an SSL/TLS client proposes to resume a session but that session cannot be found in the internal session cache (peep SSL_CTX_set_session_cache_mode(3)). also important: this one is SSL/TLS server only 🖥️

the getters ⭐

SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and SSL_CTX_sess_get_get_cb() retrieve the function pointers of the callback functions you provided. and if a callback function hasn't been set? you get the NULL pointer back. that's it. that's the answer 🙈

so why do these exist, fr fr 🧚

in order to allow external session caching, synchronization with the internal session cache is realized via callback functions. and inside these callback functions, the session can be saved to disk or put into a database using the d2i_SSL_SESSION(3) interface. that's the whole point, that's the assignment, ate 💖

the three callbacks, one by one 🎀

new_session_cb() 🆕

called whenever a new session has been negotiated and session caching is enabled (again, SSL_CTX_set_session_cache_mode(3)). it gets passed the ssl connection and the ssl session sess. and here's the plot twist: if the callback returns 0, the session will be immediately removed again 😭 so like... return 0 only if you actually mean it.

remove_session_cb() 🗑️

called whenever the SSL engine removes a session from the internal cache. when does that happen, you ask? when the session is removed because it's expired, or when a connection was not shut down cleanly. it also happens for all sessions in the internal session cache when SSL_CTX_free(3) is called — yes, all of them, every last one 💀

it's passed the ctx and the ssl session sess. and it does not provide any feedback. no return value, no notes, no thoughts, just vibes 🫶

get_session_cb() 🔍

this one is only called on SSL/TLS servers, with the session id proposed by the client. and listen — it is always called, also when session caching was disabled. iconic behaviour honestly 👑

it gets passed the ssl connection, plus the session id of length length at the memory location data. then with the parameter copy, the callback can require the SSL engine to increment the reference count of the SSL_SESSION object.

⚠️ and this is the important part, bestie: normally the reference count is not incremented, and therefore the session must not be explicitly freed with SSL_SESSION_free(3). don't do it. put the free() down 🔥

---

🌈 SEE ALSO 🌈

d2i_SSL_SESSION(3), ssl(3), SSL_CTX_flush_sessions(3), SSL_CTX_free(3), SSL_CTX_set_session_cache_mode(3), SSL_SESSION_free(3)

like pls go read these, they're all linked up and they all slay in their own way ✨

---

👑 HISTORY 👑

• SSL_CTX_sess_set_new_cb(), SSL_CTX_sess_set_get_cb(), SSL_CTX_sess_get_new_cb(), and SSL_CTX_sess_get_get_cb() — first appeared in SSLeay 0.6.0 ⭐
• SSL_CTX_sess_set_remove_cb() and SSL_CTX_sess_get_remove_cb() — first appeared in SSLeay 0.8.0 🦋
• and these functions have been available since OpenBSD 2.4 💜

---

and that's the page, bestie!! 🎀 mwah 💋

Debian 🌸 August 25, 2026 🌸 SSL_CTX_SESS_SET_GET_CB(3) — go forth and cache externally, ily 🫶💖