ssl_session_cache_api(3)

✨ NAME ✨

ssl_session_cache_api — the TLS session cache API, bestie 💖

(yeah, that's a manual page from the ssl section 3 manuals, and it's about letting you swap out how TLS stores its sessions. iconic.)

---

🦋 DESCRIPTION 🦋

Okay so real talk: this module lays down the API for the TLS session cache (pre TLS-1.3, just so we're clear 👀). The whole point of it is that the data storage scheme is swappable — you can literally define your own callback module that implements this API and boom, your storage, your rules. main character energy fr fr 👑

---

💖 DATA TYPES 💖

• -opaque partial_key() — the opaque chunk of the key. Don't stress about it, the callback does not need to handle it. it's giving "not my problem" 💅
• -opaque session() — the actual session data that gets stored for each session. this is the good stuff.
• session_cache_key() :: {partial_key(), ssl:session_id()} — a key to an entry in the session cache. that's the whole vibe: a partial_key() and an ssl:session_id() in a little tuple together, adorable 🥺
• session_cache_ref() :: any() — a term you can use to reference the cache. literally anything, whatever you want, go off.

---

🎀 CALLBACKS 🎀

🌸 delete(CacheRef, Key)

Deletes a cache entry. bye bestie, gone, no notes 🫶

Heads up: this one is only called from the cache handling process.

🌸 foldl(Fun, Acc0, CacheRef)

Calls Fun(Elem, AccIn) on successive elements of the cache, starting with AccIn == Acc0. it's the classic fold, she's a legend ⭐

Fun/2 must return a new accumulator, which gets passed to the next call. The function returns the final value of the accumulator. And if the cache is empty? You just get Acc0 right back. nothing happened, and that's fine 💜

NOTE: Since OTP-23.3 this function is only used on the client side and does not need to be implemented for a server cache. so if you're server side you can lowkey skip it 🙈

🌸 init(InitArgs)

Performs possible initializations of the cache and returns a reference to it — that reference then gets used as a parameter to the other API functions. it's the whole origin story ✨

It's called by the cache handling process's init function, so it's got all the same requirements as a normal process init function would. And here's the fun part: this function is called twice when starting the SSL application — once with the role client and once with the role server, because the SSL application has to be prepared to take on both roles. she contains multitudes 🌈

It includes the property {role, client | server} in the init argument list. Currently that's the only predefined property, but there can also be user-defined properties. See also the application environment variable session_cb_init_args.

🌸 lookup(CacheRef, Key)

Looks up a cache entry. Has to be callable from any process. no gatekeeping here 💅

🌸 select_session(CacheRef, Server)

Selects sessions that can be reused — meaning sessions that include PartialKey in their key. Also has to be callable from any process. let's reuse, bestie, it's eco-friendly 🌱

NOTE: Since OTP-23.3 this function is only used on the client side and does not need to be implemented for a server cache. server besties, you're off the hook 😭

🌸 size(CacheRef)

Returns the number of sessions in the cache.

And now the dramatic part: if the size exceeds the maximum number of sessions, the current cache entries will be invalidated regardless of their remaining lifetime. yes, even the fresh ones. even the cute ones. 💀 Has to be callable from any process.

🌸 terminate(CacheRef)

Takes care of possible cleanup that's needed when the cache handling process terminates. closing time, turn the lights off, you did great 🕯️

🌸 update(CacheRef, Key, Session)

Caches a new session or updates an already cached one. new or glow-up, we love both 🦋

Heads up: this one is only called from the cache handling process.

---

that's the whole API, babe — every callback, every opaque, every note, nothing skipped, no cap 🧚‍♀️💖

and that's a wrap from Ericsson AB, shipping ssl 11.7.5 — go build something gorgeous with it, k byeee 🎀✨👑