SSL_SET_SESSION_SECRET_CB(3SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

💖 SSL_set_session_secret_cb — the session secret callback situation 💖

okay bestie, so this is a page from the OpenSSL manual, section 3SSL, and we're talking about SSL_set_session_secret_cb and tls_session_secret_cb_fn. it's giving very niche, very specific, and honestly? we love a girl with a very particular job. let's get into it 💅

✨ NAME ✨

SSL_set_session_secret_cb, tls_session_secret_cb_fn — set the session secret callback, no cap

🌸 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 name says (iconic of it honestly): it sets the session secret callback — that's session_secret_cb — plus an optional argument arg that gets handed off to that callback every time it's called. 🫶

⚠️ listen carefully bestie: this is only useful if you're implementing EAP-FAST (RFC4851). and like, the mere presence of this callback changes the internal OpenSSL TLS state machine so it matches the modified TLS behaviour described in RFC4851. so do not use this callback unless you are implementing EAP-FAST. that's the rule. periodt.

the callback is expected to set the master secret it wants used by filling in the data that *secret points at. the size of the secret buffer starts out available in *secret_len, and the callback is allowed to update that — but it must not be larger than the initial value. so cute, so constrained. 🙈

on the server side 👑 the set of ciphersuites offered by the peer shows up in the peer_ciphers stack. optionally, the callback can pick its preferred ciphersuite by setting it in *cipher.

on the client side 💜 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, ngl, it does not affect the ciphersuite the server selects. so it's a little decorative, a little main character, but not in charge. 💀

also the callback gets one more thing: the additional argument arg, which is literally the argument that was passed to the original SSL_set_session_secret_cb() call. full circle, we love to see it. ✨

💜 RETURN VALUES 💜

SSL_set_session_secret_cb() returns 1 on success and 0 on failure. slay or don't, no in-between. 🌈

and if the callback returns 1, that means it successfully set the secret. a return value of 0 means the secret has not been set — and on the client, that causes an immediate abort of the handshake. 🚨 like, we are DONE here. no secret, no handshake, no vibe check passed.

🎀 SEE ALSO 🎀

go read those too, bestie, iykyk 📚✨

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

okay that's the whole page!! thanks for reading my little unix rant, you ate that 🫶 this was OpenSSL version 4.0.3, dated 2026-09-29, and it lives under the name SSL_SET_SESSION_SECRET_CB(3SSL). mwah, bye bestie 💖🧚🌸

📦 where this page comes from