SSL_CTX_SET_..._GENERATE_CB(3ossl)

📦
version 3.5.9 · 8 versions
, in fedora 43, fedora 44

💅 NAME 💅

okay bestie, welcome to SSL_CTX_SET_..._GENERATE_CB from the 3ossl manual — yes the title is doing the most with those ellipses, she's mysterious like that. 🎀

This page is all about these four icons 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

and they're literally just callback functions for stateless TLS1.3 cookies. cookies!! not the edible kind unfortunately 😭 but still slay.

✨ 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));

like look at those function pointer signatures. she's giving function pointer realness. 🫶

🌸 DESCRIPTION 🌸

okay so let's break these four down one by one, no skipping, we're doing the whole set 💖

🍓 the stateless ones (TLS1.3 girlies)

SSL_CTX_set_stateless_cookie_generate_cb() sets the callback that SSL_stateless(3) uses to generate the application-controlled portion of the cookie handed to clients in the HelloRetryRequest. And when does that get sent? As a response to a ClientHello that showed up with a missing or invalid cookie. rude of them honestly. 🙈

gen_stateless_cookie_cb() has rules, and she follows them:

  • it must write at most SSL_COOKIE_LENGTH bytes into cookie
  • it must write the number of bytes written to cookie_len
  • and if a cookie just cannot be generated? a zero return value can be used to abort the handshake. dramatic but valid. 💀

SSL_CTX_set_stateless_cookie_verify_cb() sets the callback that SSL_stateless(3) uses to figure out whether the application-controlled portion of a ClientHello cookie is actually valid. the cookie data is pointed to by cookie, and its length is cookie_len. a nonzero return value from verify_stateless_cookie_cb() is how you say "yes bestie, this cookie is valid." ✅

ngl the best 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 already did the vibe check for you. 👑

🦋 the DTLS ones

SSL_CTX_set_cookie_generate_cb() sets the callback used by DTLSv1_listen(3) to generate the cookie given to clients in the HelloVerifyRequest — transmitted as a response to a ClientHello with a missing or invalid cookie, same energy as above.

app_gen_cookie_cb() must:

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

SSL_CTX_set_cookie_verify_cb() sets the callback used by DTLSv1_listen(3) to determine whether the cookie in a ClientHello is valid. the cookie data is pointed to by cookie and is of length cookie_len. a nonzero return value from app_verify_cookie_cb() communicates that the cookie is valid. ✅

🚨 okay important one, do not skip this: the integrity of the cookie is NOT verified by OpenSSL here. that's an application responsibility. meaning it's on you, bestie. the stateless one had HMAC doing the work, this one does not. keep that energy in mind. 😤

🌈 RETURN VALUES 🌈

neither function returns a value. that's it, that's the whole section. no notes. 💅

⭐ SEE ALSO ⭐

go read those, they're the supporting cast and they ate. 🔥

👑 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 established, they're veterans. 🎀

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

okay and that's the whole page bestie, you understood it, you slayed it, you're literally the main character of TLS handshakes now 🦋✨ this was OpenSSL 3.5.9, dated 2026-09-29, and yes she's iconic, mwah 💋🧚‍♀️

📦 where this page comes from