LIBRESSL-SSL_CTX_SET_MSG_CALLBACK(3)

💅 SSL_CTX_SET_MSG_CALLBACK(3) — like, the manual page, but make it make sense

okay bestie so this is a page from the libssl / libcrypto manuals (yes, that libssl — the crypto one, we stan) and it's all about installing a callback so you can eavesdrop on your own protocol messages. not in a shady way!! in a "my own code, my own TLS, I just wanna watch" way. 🦋

---

✨ NAME ✨

SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_set_msg_callback_arg — install a callback for observing protocol messages 👀✨

---

🌸 SYNOPSIS 🌸

first, the vibe check — you're pulling in the library:

library “libssl” libcrypto #include <openssl/ssl.h>

then the four functions, exactly as they are, no cap:

void
SSL_CTX_set_msg_callback(SSL_CTX *ctx,
    void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));

void
SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);

void
SSL_set_msg_callback(SSL *ssl,
    void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));

void
SSL_set_msg_callback_arg(SSL *ssl, void *arg);

---

🎀 DESCRIPTION 🎀

so SSL_CTX_set_msg_callback() and SSL_set_msg_callback() are how you define a message callback function cb that just… watches. literally all SSL/TLS protocol messages (handshake messages and friends) that get received or sent — it's giving security camera but make it TLS. 🔥

and then SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg() set the argument arg that gets handed to your callback function, and that one's yours — put whatever you want in it, the library is not gonna touch it, it's for arbitrary application use, periodt.

now the ctx-vs-ssl of it all:

• SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() set up the default settings that get copied onto new SSL objects by SSL_new(3). so it's like the blueprint energy. ✨
• SSL_set_msg_callback() and SSL_set_msg_callback_arg() change the actual settings on a specific SSL object. main character behaviour, only affects that one.

and if you pass a NULL pointer for cb? callback disabled. done. bye. 💅

---

💖 what the callback arguments mean 💖

when the SSL/TLS library calls cb for a protocol message, here's the tea on every argument:

• write_p — this flag is 0 when a protocol message has been received and 1 when a protocol message has been sent. so it's the "which direction" girlie.
• version — the protocol version according to which the protocol message is interpreted by the library, like TLS1_VERSION, TLS1_1_VERSION, TLS1_2_VERSION, DTLS1_VERSION, or DTLS1_2_VERSION. slay, versioned.
• content_type — one of the ContentType values defined in the protocol spec. specifically SSL3_RT_CHANGE_CIPHER_SPEC, SSL3_RT_ALERT, SSL3_RT_HANDSHAKE, but never SSL3_RT_APPLICATION_DATA — because the callback only fires for protocol messages. no app data, we don't do that here. 🙈
• buf, len — buf points to a buffer holding the protocol message, which consists of len bytes. ⚠️ heads up: the buffer is no longer valid after the callback function has returned — so if you need it, copy it, don't keep the pointer. she's gone bestie.
• ssl — the SSL object that received or sent the message. iconic.
• arg — the user-defined argument you optionally defined with SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg(). that's your little gift to yourself. 🎁

---

🧚 the fine print (read it, bestie) 🧚

protocol messages are passed to the callback function after decryption and fragment collection where applicable. so basically:

record boundaries are not visible. 😭 the callback sees reassembled, decrypted goodness, not the raw wire chunks.

and, important: if processing a received protocol message results in an error, the callback function may not be called. for example, the callback function will never see messages that are considered too large to be processed. so like, no callback is not always "no message" — sometimes it's just "message was too much". 💀

also, bc of automatic protocol version negotiation, version is not necessarily the protocol version used by the sender of the message. iconic example: if a TLS 1.0 ClientHello message is received by an SSL 3.0-only server, version will be SSL3_VERSION. so read it as "how we interpreted it", not "what the sender was running". 🫶

---

🌈 SEE ALSO 🌈

• ssl(3)
• SSL_new(3)

go read those, iykyk 💜

---

👑 HISTORY 👑

SSL_CTX_set_msg_callback(), SSL_CTX_set_msg_callback_arg(), SSL_set_msg_callback() and SSL_set_msg_callback_arg() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2. vintage, honestly. ⭐

---

and that's the whole page, no skipped sections, no notes left behind. mwah. 💅

---

okay love u bye 🫶 this page is from the Debian build, dated June 8, 2025, and honestly? it ate. 🌸✨🎀