SSL_CTX_SET_S...ON_CACHE_MODE(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

💅 SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode — bestie says let's talk session caching (this is the 3SSL page, from the OpenSSL fam)

okay so real talk, these two functions are the on/off switch and the status bar for your session cache. one sets it, one tells you what it currently is. that's the whole job. iconic, honestly.

✨ SYNOPSIS ✨

#include <openssl/ssl.h>

long SSL_CTX_set_session_cache_mode(SSL_CTX *ctx, long mode);
long SSL_CTX_get_session_cache_mode(SSL_CTX *ctx);

🌸 DESCRIPTION 🌸

  • SSL_CTX_set_session_cache_mode() — turns session caching on or off, lowkey, by setting the operational mode for ctx to mode. slay.
  • SSL_CTX_get_session_cache_mode() — hands you back the cache mode you're currently rocking.

👑 NOTES 👑

so the OpenSSL library can store SSL/TLS sessions and pull them back out later for reuse. no cap. and here's the tea: those sessions can just live in memory, per ctx. and if you're out here juggling more than one SSL_CTX object, bestie, the sessions are unique for each SSL_CTX object. no sharing, they don't mix. 🫶

for a session to actually get reused, a client has to send the session's id to the server. and it can only send exactly one id. like, one. that's it. then the server either agrees to reuse that session or it starts a full handshake to create a whole new session. it's giving "commit or start over." 😭

a server will look the session up in its internal session storage. and if the session isn't in internal storage, or if lookups for the internal storage have been deactivated (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP), the server will try the external storage, if there is any. so like, the external one is the backup plan.

and listen — since a client may try to reuse a session that was intended for use in a different context, the session id context must be set by the server. go check SSL_CTX_set_session_id_context(3). non-negotiable, fr fr.

here are all the session cache modes and modifiers, and yes we're doing all of them:

  • SSL_SESS_CACHE_OFF — no session caching for client or server takes place. zero. none. the vibe is "we're not doing that." 💀
  • SSL_SESS_CACHE_CLIENT — client sessions get added to the session cache. but here's the catch: there's no reliable way for the OpenSSL library to know whether a session should be reused or which session to choose, because of the abstract BIO layer — the SSL engine just doesn't have details about the connection. so the application has to pick the session to be reused itself, using SSL_set_session(3). this option is not activated by default. you gotta opt in, bestie.
  • SSL_SESS_CACHE_SERVER — server sessions get added to the session cache. when a client proposes a session to be reused, the server goes looking for the corresponding session, first in the internal session cache (unless SSL_SESS_CACHE_NO_INTERNAL_LOOKUP is set), then second in the external cache if it's available. and if the session is found, the server will try to reuse it. oh and this one? this is the default. the main character. 👑
  • SSL_SESS_CACHE_BOTH — enables both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time. why choose. 🦋
  • SSL_SESS_CACHE_NO_AUTO_CLEAR — normally the session cache gets checked for expired sessions every 255 connections, using the SSL_CTX_flush_sessions(3) function. but since that can cause a delay you have zero control over, you can disable the automatic flushing and call SSL_CTX_flush_sessions(3) explicitly from your application instead. you get the wheel, no more random lag spikes. ✨
  • SSL_SESS_CACHE_NO_INTERNAL_LOOKUP — set this flag and session-resume operations on an SSL/TLS server will not automatically look up sessions in the internal cache, even if sessions are automatically stored there. and if external session caching callbacks are in use, this flag guarantees that all lookups get directed to the external cache. and since automatic lookup only applies to SSL/TLS servers, this flag does absolutely nothing on clients. no effect. nada.
  • SSL_SESS_CACHE_NO_INTERNAL_STORE — so depending on whether SSL_SESS_CACHE_CLIENT and/or SSL_SESS_CACHE_SERVER are present, sessions negotiated in an SSL/TLS handshake may be cached for possible reuse. normally a new session gets added to the internal cache plus any external session caching (callback) configured for the SSL_CTX. this flag prevents sessions from being stored in the internal cache — though your application can still add them manually using SSL_CTX_add_session(3).
note: in any SSL/TLS servers where external caching is configured, any successful session lookups in the external cache (that's for session-resume requests, iykwyk) would normally get copied into the local cache before processing continues. this flag prevents those additions to the internal cache too. sneaky little detail but so important.
  • SSL_SESS_CACHE_NO_INTERNAL — enables both SSL_SESS_CACHE_NO_INTERNAL_LOOKUP and SSL_SESS_CACHE_NO_INTERNAL_STORE at the same time. combo deal. 🌈
  • SSL_SESS_CACHE_UPDATE_TIME — updates the timestamp of the session when it's used, which increases the lifespan of the session. so the session timeout applies to last use, rather than creation time. glow-up for your sessions, they live longer now. ⭐

and the default mode, one more time for the people in the back: SSL_SESS_CACHE_SERVER. periodt.

💜 RETURN VALUES 💜

  • SSL_CTX_set_session_cache_mode() — returns the previously set cache mode. (the old one, not the new one. yes really.)
  • SSL_CTX_get_session_cache_mode() — returns the currently set cache mode.

🎀 SEE ALSO 🎀

ssl(7), SSL_set_session(3), SSL_session_reused(3), SSL_CTX_add_session(3), SSL_CTX_sess_number(3), SSL_CTX_sess_set_cache_size(3), SSL_CTX_sess_set_get_cb(3), SSL_CTX_set_session_id_context(3), SSL_CTX_set_timeout(3), SSL_CTX_flush_sessions(3)

Copyright 2001-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 OpenSSL 4.0.3, dated 2026-09-2, and yes the manpage name is literally SSL_CTX_SET_S...ON_CACHE_MODE(3SSL) because it got elided and honestly? it ate. go forth and cache responsibly. 🫶✨

📦 where this page comes from