SSL_CTX_SET_..._GENERATE_CB(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 SSL_CTX_SET_..._GENERATE_CB — bestie edition 🍪

okay so this is the 3ossl manual page, and it's literally all about cookie callback functions for stateless TLS1.3 🍪✨ (yes bestie, TLS has cookies too, iykyk)

🌸 NAME 🌸

  • 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 together they're the Callback functions for stateless TLS1.3 cookies 🎀

✨ 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… four functions, four callbacks, all vibes 💅

🦋 DESCRIPTION 🦋

SSL_CTX_set_stateless_cookie_generate_cb() sets the callback that SSL_stateless(3) uses to generate the application-controlled portion of the cookie that gets handed to clients in the HelloRetryRequest 🌈 — and that HelloRetryRequest is literally the response to a ClientHello that showed up with a missing or invalid cookie 😭🙈

so gen_stateless_cookie_cb() has to write at most SSL_COOKIE_LENGTH bytes into cookie, and must write the number of bytes it wrote into cookie_len ✍️ no cap.

and if a cookie just cannot be generated? a zero return value can be used to abort the handshake. periodt. 💀

SSL_CTX_set_stateless_cookie_verify_cb() sets the callback 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 is of length cookie_len 🫶

a nonzero return value from verify_stateless_cookie_cb() tells everyone "yep bestie, this cookie is valid" ✅

okay and this part is lowkey iconic: the integrity of the entire cookie — including the application-controlled portion — is automatically verified by HMAC before verify_stateless_cookie_cb() even gets called 😌✨ so you're not doing that job, it's already done.

SSL_CTX_set_cookie_generate_cb() sets the callback DTLSv1_listen(3) uses to generate the cookie provided to clients in the HelloVerifyRequest 🌸 — transmitted in response to a ClientHello with a missing or invalid cookie, same energy as before 😭

app_gen_cookie_cb() must write at most DTLS1_COOKIE_LENGTH bytes into cookie, and must write the number of bytes written to cookie_len ✍️ (yes it's a different constant than the TLS one, keep up bestie 💅)

again — if a cookie cannot be generated, a zero return value can be used to abort the handshake 🫠

SSL_CTX_set_cookie_verify_cb() sets the callback DTLSv1_listen(3) uses to decide whether the cookie in a ClientHello is valid 👑

cookie data is pointed to by cookie, length cookie_len 🎀 a nonzero return value from app_verify_cookie_cb() means the cookie is valid ✅

BIG difference here though and pls don't miss it: the integrity of the cookie is not verified by OpenSSL. that's an application responsibility 🙈 you're the main character on this one, fr fr.

⭐ RETURN VALUES ⭐

neither function returns a value. like, none. zero. nothing. they're just setters doing their little setter thing 💅

🌈 SEE ALSO 🌈

👑 HISTORY 👑

SSL_CTX_set_stateless_cookie_generate_cb() and SSL_CTX_set_stateless_cookie_verify_cb() were added in OpenSSL 1.1.1 ✨ (the other two were already living their truth, iykyk)

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

k bye bestie, this was OpenSSL 3.5.0, dated 2026-09-25 — signed, sealed, and slayed by the SSL_CTX_SET_..._GENERATE_CB(3ossl) girls 🫶💖

📦 where this page comes from