SSL_SET_SESSION_SECRET_CB(3ossl)

💖 SSL_SET_SESSION_SECRET_CB 💖

okay bestie, welcome to SSL_set_session_secret_cb(3ossl) — yes it's a mouthful, yes it's from OpenSSL, and yes we're gonna get through it together. grab a snack 🍓

---

✨ NAME ✨

SSL_set_session_secret_cb, tls_session_secret_cb_fn — the whole "set the session secret callback" situation 💅

---

🎀 SYNOPSIS 🎀

#include <openssl/ssl.h>

typedef int (*tls_session_secret_cb_fn)(SSL *s, void *secret, int *secret_len,
                                        STACK_OF(SSL_CIPHER) *peer_ciphers,
                                        const SSL_CIPHER **cipher, void *arg);

int SSL_set_session_secret_cb(SSL *s,
                              tls_session_secret_cb_fn session_secret_cb,
                              void *arg);

---

🌸 DESCRIPTION 🌸

SSL_set_session_secret_cb() sets the session secret callback to be used, which is the session_secret_cb, plus an optional argument (arg) that gets passed along to that callback whenever it's called. that's the whole vibe.

and listen — this is only useful for an implementation of EAP-FAST (RFC4851). like, that's it, that's the assignment. the mere presence of the callback also modifies the internal OpenSSL TLS state machine so it matches the modified TLS behaviour described in RFC4851. so basically:

do NOT use this callback unless you're literally implementing EAP-FAST. it is not a general-purpose toy, bestie. respect the state machine. 🫶

here's what the callback is expected to do — it sets the master secret that's going to be used by filling in the data that *secret points at. the size of that secret buffer starts out available in *secret_len, and the callback is allowed to update it… but it must not be larger than the initial value. no stretching, no growing, we stay within the lines. 🎀

server side energy: the set of ciphersuites that the peer offered shows up in the peer_ciphers stack. optionally, the callback can pick the preferred ciphersuite by setting it in *cipher. queen behaviour, choosing her own cipher. 👑

client side energy: the peer_ciphers stack will always be NULL. the callback may still specify the preferred cipher in *cipher, and that will get associated with the SSL_SESSION — but heads up, it does not affect the ciphersuite that the server selects. so like, it's giving opinion, not control. 😭

the callback also gets handed one extra argument in arg — and that's literally the argument you passed to the original SSL_set_session_secret_cb() call. full circle, no cap. 🔥

---

🌈 RETURN VALUES 🌈

SSL_set_session_secret_cb() returns 1 on success and 0 on failure. simple, clean, iconic.

and if the callback returns 1, that means it successfully set the secret. if it returns 0, that means the secret has not been set — and on the client side, that causes an immediate abort of the handshake. dramatic? yes. correct? also yes. 💀

---

🦋 SEE ALSO 🦋

• ssl(7)
• SSL_get_session(3)

---

👑 COPYRIGHT 👑

Copyright 2024 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 one's from OpenSSL 3.5.9, dated 2026-09-29 — go forth, set your session secret callback, and only do it for EAP-FAST, okay? mwah. 💅✨