SSL_CTX_SET_...DING_CALLBACK(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

🎀 SSL_CTX_set_record_padding_callback + friends: the TLS 1.3 record padding crew (3ossl, OpenSSL) 🎀

okay so bestie, this is the OpenSSL manual page for the whole little friend group of functions that install a callback to specify TLS 1.3 record padding 💅 — yes, the header calls it SSL_CTX_SET_...DING_CALLBACK(3ossl) because that name is literally too long to exist, and it lives in the 3ossl OpenSSL section. Buckle up, we're going record by record ✨

🌸 NAME 🌸

SSL_CTX_set_record_padding_callback, SSL_set_record_padding_callback, SSL_CTX_set_record_padding_callback_arg, SSL_set_record_padding_callback_arg, SSL_CTX_get_record_padding_callback_arg, SSL_get_record_padding_callback_arg, SSL_CTX_set_block_padding, SSL_CTX_set_block_padding_ex, SSL_set_block_padding, SSL_set_block_padding_ex — install callback to specify TLS 1.3 record padding 👑

that's the whole squad, they all show up in this one page, no cap 🫶

✨ SYNOPSIS ✨

#include <openssl/ssl.h>

void SSL_CTX_set_record_padding_callback(SSL_CTX *ctx, size_t (*cb)(SSL *s, int type, size_t len, void *arg));
int SSL_set_record_padding_callback(SSL *ssl, size_t (*cb)(SSL *s, int type, size_t len, void *arg));

void SSL_CTX_set_record_padding_callback_arg(SSL_CTX *ctx, void *arg);
void *SSL_CTX_get_record_padding_callback_arg(const SSL_CTX *ctx);

void SSL_set_record_padding_callback_arg(SSL *ssl, void *arg);
void *SSL_get_record_padding_callback_arg(const SSL *ssl);

int SSL_CTX_set_block_padding(SSL_CTX *ctx, size_t block_size);
int SSL_set_block_padding(SSL *ssl, size_t block_size);
int SSL_CTX_set_block_padding_ex(SSL_CTX *ctx, size_t app_block_size, size_t hs_block_size);
int SSL_set_block_padding_ex(SSL *ssl, size_t app_block_size, size_t hs_block_size);

look at all those size_ts, we love a type that ate 💀

🦋 DESCRIPTION 🦋

the callback installers 🔥

SSL_CTX_set_record_padding_callback() or SSL_set_record_padding_callback() can be used to assign a callback function cb to specify the padding for TLS 1.3 records. The value set in ctx is copied to a new SSL by SSL_new(). Kernel TLS is not possible if the record padding callback is set, and the callback function cannot be set if Kernel TLS is already configured for the current SSL object. it's giving "you can't sit with us" energy, but like, in both directions 🙈

the arg setters and getters 🎀

SSL_CTX_set_record_padding_callback_arg() and SSL_set_record_padding_callback_arg() assign a value arg that is passed to the callback when it is invoked. The value set in ctx is copied to a new SSL by SSL_new(). so the ctx version is literally the main character and the SSL version is the nepo baby that inherits everything ✨

SSL_CTX_get_record_padding_callback_arg() and SSL_get_record_padding_callback_arg() retrieve the arg value that is passed to the callback. reading it back, we love a round trip 💖

the block padding squad 🧚

SSL_CTX_set_block_padding() and SSL_set_block_padding() pads the record to a multiple of the block_size. A block_size of 0 or 1 disables block padding. The limit of block_size is SSL3_RT_MAX_PLAIN_LENGTH. don't get too big for your boots bestie, that's the ceiling 🌈

SSL_CTX_set_block_padding_ex() and SSL_set_block_padding_ex() do similarly but allow the caller to separately specify the padding block size to be applied to handshake and application data messages. two sizes, two vibes, one function 👑

how the callback actually gets called ⭐

The callback is invoked for every record before encryption. The type parameter is the TLS record type that is being processed; may be one of SSL3_RT_APPLICATION_DATA, SSL3_RT_HANDSHAKE, or SSL3_RT_ALERT. The len parameter is the current plaintext length of the record before encryption. The arg parameter is the value set via SSL_CTX_set_record_padding_callback_arg() or SSL_set_record_padding_callback_arg(). iykyk — that's the whole callback contract, right there 🫶

the QUIC situation 💀

These functions cannot be used with QUIC SSL objects. SSL_set_record_padding_callback() and SSL_set_block_padding() fail if called on a QUIC SSL object. sorry QUIC girlies, this party is TLS 1.3 only 🚫

🌟 RETURN VALUES 🌟

  • SSL_CTX_get_record_padding_callback_arg() and SSL_get_record_padding_callback_arg() return the arg value assigned in the corresponding set functions. yes, they hand you back your own stuff 🎁
  • SSL_CTX_set_block_padding() and SSL_set_block_padding() return 1 on success or 0 if block_size is too large. simple, iconic, no notes 💅
  • The cb returns the number of padding bytes to add to the record. A return of 0 indicates no padding will be added. A return value that causes the record to exceed the maximum record size (SSL3_RT_MAX_PLAIN_LENGTH) will pad out to the maximum record size. ok so basically if you overshoot, it just caps at the max, it does NOT explode, we love a graceful limit ✨
  • SSL_CTX_get_record_padding_callback_arg() returns 1 on success or 0 if the callback function is not set because Kernel TLS is configured for the SSL object. (yes, this one is listed as returning 1/0 even though the synopsis says void * — we just report what the page says, no editing the lore 🙈)

💜 NOTES 💜

  • The default behavior is to add no padding to the record. clean, minimal, no extra baggage 🎀
  • A user-supplied padding callback function will override the behavior set by SSL_set_block_padding() or SSL_CTX_set_block_padding(). Setting the user-supplied callback to NULL will restore the configured block padding behavior. so the callback is the main character and the block padding is the backup dancer, but the backup dancer gets their spot back when the star leaves 🫶
  • These functions only apply to TLS 1.3 records being written. reading is not invited to this party 🌸
  • Padding bytes are not added in constant-time. ⚠️ fr fr, keep that in mind if you're being all timing-attack-paranoid

🌈 SEE ALSO 🌈

go read those next bestie, they're the prequels 🦋

👑 HISTORY 👑

  • The record padding API was added for TLS 1.3 support in OpenSSL 1.1.1. a classic, truly vintage ✨
  • The return type of SSL_CTX_set_record_padding_callback() function was changed to int in OpenSSL 3.0. glow-up era 💅
  • The functions SSL_set_block_padding_ex() and SSL_CTX_set_block_padding_ex() were added in OpenSSL 3.4. the new girls on the block 🎀

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

and that's the page!! 💖 written for OpenSSL 3.5.0, dated 2026-09-2, SSL_CTX_SET_...DING_CALLBACK(3ossl) — mwah, go pad some records responsibly bestie 😭🔥
📦 where this page comes from