SSL_CTX_SET_S...E_GENERATE_CB(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

okay so bestie, you know how TLS1.3 and DTLS wanna check that a client is actually at the address they claim to be at, before doing all the expensive handshake stuff? that's what cookie callbacks are for. and this page is literally the whole lore on the four functions that let your app control the cookie. it's giving gatekeeper energy, but make it cryptographic. ✨

this one lives in the OpenSSL manual, section 3SSL. so cozy up, grab a beverage, and let's go. 🫶

✨ NAME ✨

so these four besties right here:

  • SSL_CTX_set_stateless_cookie_generate_cb
  • SSL_CTX_set_stateless_cookie_verify_cb
  • SSL_CTX_set_cookie_generate_cb
  • SSL_CTX_set_cookie_verify_cb

are the Callback functions for stateless TLS1.3 cookies. that's the whole vibe. 👑

🌸 SYNOPSIS 🌸

#include <openssl/ssl.h>

void SSL_CTX_set_stateless_cookie_generate_cb(
    SSL_CTX *ctx,
    int (*gen_stateless_cookie_cb) (SSL *ssl,
                                    unsigned char *cookie,
                                    size_t *cookie_len));
void SSL_CTX_set_stateless_cookie_verify_cb(
    SSL_CTX *ctx,
    int (*verify_stateless_cookie_cb) (SSL *ssl,
                                       const unsigned char *cookie,
                                       size_t cookie_len));

void SSL_CTX_set_cookie_generate_cb(SSL_CTX *ctx,
                                    int (*app_gen_cookie_cb) (SSL *ssl,
                                                              unsigned char
                                                              *cookie,
                                                              unsigned int
                                                              *cookie_len));
void SSL_CTX_set_cookie_verify_cb(SSL_CTX *ctx,
                                  int (*app_verify_cookie_cb) (SSL *ssl,
                                                               const unsigned
                                                               char *cookie,
                                                               unsigned int
                                                               cookie_len));

look at those function pointers. chef's kiss. no cap, that indentation is a whole art form. 💅

🎀 DESCRIPTION 🎀

🌈 the stateless ones (TLS1.3, glamorous, HMAC-protected)

SSL_CTX_set_stateless_cookie_generate_cb() — this sets the callback that SSL_stateless(3) uses to generate the application-controlled portion of the cookie it hands to clients inside the HelloRetryRequest. and when does that HelloRetryRequest go out? as a response to a ClientHello that has a missing or invalid cookie. rude of them, honestly.

so gen_stateless_cookie_cb() has a job and it's very serious:

  • it must write at most SSL_COOKIE_LENGTH bytes into cookie 👀
  • it must write the number of bytes written into cookie_len 📏
  • and if a cookie just cannot be generated? you can return zero to abort the handshake. dramatic exit, love that for you. 💀

SSL_CTX_set_stateless_cookie_verify_cb() — this sets the callback SSL_stateless(3) uses to decide whether the application-controlled portion of a ClientHello cookie is valid. here's the tea:

  • the cookie data is pointed to by cookie
  • and it's of length cookie_len
  • a nonzero return value from verify_stateless_cookie_cb() means "yes bestie, this cookie is valid" ✅

and here's the iconic part — the integrity of the entire cookie, including the application-controlled portion, is automatically verified by HMAC before verify_stateless_cookie_cb() is even called. so OpenSSL does the vibes check for you first. 🧚

🦋 the regular ones (DTLS, where YOU do the integrity work)

SSL_CTX_set_cookie_generate_cb() — this sets the callback DTLSv1_listen(3) uses to generate the cookie handed to clients in the HelloVerifyRequest. and yes, it's transmitted as a response to a ClientHello with a missing or invalid cookie. same energy, different protocol. 🙈

app_gen_cookie_cb() must:

  • write at most DTLS1_COOKIE_LENGTH bytes into cookie
  • write the number of bytes written into cookie_len
  • and if a cookie can't be generated, a zero return value can be used to abort the handshake. bye! ✌️

SSL_CTX_set_cookie_verify_cb() — sets the callback DTLSv1_listen(3) uses to determine whether the cookie in a ClientHello is valid.

  • the cookie data is pointed to by cookie
  • it's of length cookie_len
  • a nonzero return value from app_verify_cookie_cb() says "valid, periodt" ✅
⚠️ okay major heads-up bestie: with this one, the integrity of the cookie is NOT verified by OpenSSL. that is an application responsibility. it's giving you're on your own, babe. do not forget it. 😭

🌟 RETURN VALUES 🌟

Neither function returns a value. nope, not a one. they're void and they know it. 💅

👀 SEE ALSO 👀

go read those next, i'm literally begging. 🫶

📜 HISTORY 📜

SSL_CTX_set_stateless_cookie_generate_cb() and SSL_CTX_set_stateless_cookie_verify_cb() were added in OpenSSL 1.1.1. so they've been around, they're not new money. ⭐

Copyright 2018 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 was OpenSSL 4.0.3, dated 2026-09-2, and yes the page title is SSL_CTX_SET_S...E_GENERATE_CB(3SSL) — that abbreviation ate and left no crumbs. now go verify those cookies. slay. 💖✨

📦 where this page comes from