SSL_SET_SESSION_SECRET_CB(3ossl)

💅 SSL_SET_SESSION_SECRET_CB — set the session secret callback ✨

okay so this is SSL_SET_SESSION_SECRET_CB(3ossl), bestie — it lives in the OpenSSL manual fam, and it's genuinely a niche little icon. Let's get into it 🫶

---

🌸 NAME 🌸

SSL_set_session_secret_cb, tls_session_secret_cb_fn — set the session secret callback 💖

---

✨ 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 🦋

So SSL_set_session_secret_cb() does exactly what the girlies expect: it sets the session secret callback to be used (session_secret_cb), plus an optional argument (arg) that gets passed along to that callback whenever it's called. Literally just wiring it up 💅

⚠️ but like, listen — this is only useful for an implementation of EAP-FAST (RFC4851). no cap.

And here's the part that's lowkey a big deal: the presence of the callback also modifies the internal OpenSSL TLS state machine to match the modified TLS behaviour as described in RFC4851. Sooo… yeah. This callback should not be used except when implementing EAP-FAST. periodt. do not mess with it otherwise 🙈

---

🎀 what the callback actually has to do 🎀

The callback is expected to set the master secret to be used by filling in the data pointed to by *secret. Think of it like: here's the buffer, go fill it in, bestie ✍️

The size of the secret buffer is initially available in *secret_len, and the callback may update it — but it must not be larger than the initial value. respect the bounds or perish 💀

🌈 on the server side

The set of ciphersuites offered by the peer is provided in the peer_ciphers stack. Optionally, the callback may select the preferred ciphersuite by setting it in *cipher — your call, main character energy 👑

🧚 on the client side

The peer_ciphers stack will always be NULL. Always. Not sometimes-null, not maybe-null, NULL 🫠

The callback may still specify the preferred cipher in *cipher, and this will be associated with the SSL_SESSION — but (and this is the important bit) it does not affect the ciphersuite selected by the server. so fr fr, don't expect it to change what the server picks 💅

🍓 and one more thing

The callback is also supplied with an additional argument in arg, which is literally the argument that was provided to the original SSL_set_session_secret_cb() call. full circle moment 🔥

---

👑 RETURN VALUES 👑

• SSL_set_session_secret_cb() — returns 1 on success and 0 on failure. slay ✨
• the callback itself — if it returns 1, that indicates it has successfully set the secret 💖 a return value of 0 indicates that the secret has not been set — and on the client, that will cause an immediate abort of the handshake 😭 like, full stop, handshake over.

---

🌸 SEE ALSO 🌸

• ssl(7)
• SSL_get_session(3)

go read those too, iykyk 🫶

---

💜 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>.

---

so yeah, that's the whole vibe check 💅 this page is from OpenSSL 3.5.0, dated 2026-09-25, and it's filed under SSL_SET_SESSION_SECRET_CB(3ossl) — go forth and only implement EAP-FAST with it, bestie 😭🎀🦋