SSL_CTX_SET_...DING_CALLBACK(3ossl)

📦
version 15.1 · 3 versions
, in freebsd 15.1

✨ SSL_CTX_set_record_padding_callback(3ossl) ✨

Okay so bestie, this is the OpenSSL manual page for SSL_CTX_SET_...DING_CALLBACK(3ossl) and it's literally all about TLS 1.3 record padding — like, the way your data gets padded before encryption so it's all nice and blocky. No cap, this is the glow-up your record layer didn't know it needed 💅✨

🌸 NAME 🌸

Here's the whole squad of functions this page covers, and yes, they all ate:

  • 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

All of these are here to install a callback that specifies the padding for TLS 1.3 records — like, they're the main character energy for your padding setup 🎀

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

🧚 DESCRIPTION 🧚

Okay so picture this: you want to control exactly how much padding gets added to your TLS 1.3 records before they get encrypted. That's literally what SSL_CTX_set_record_padding_callback() and SSL_set_record_padding_callback() are for — they assign a callback function cb that decides the padding for TLS 1.3 records. The value you set in ctx gets copied to a new SSL object by SSL_new(). But heads up bestie, Kernel TLS is not possible if the record padding callback is set, and you can't set the callback if Kernel TLS is already configured for the current SSL object. So it's one or the other, no cap 💀

Then we've got SSL_CTX_set_record_padding_callback_arg() and SSL_set_record_padding_callback_arg() — these assign a value arg that gets passed to the callback when it's invoked. The value set in ctx is copied to a new SSL by SSL_new(). And if you need to get that value back, SSL_CTX_get_record_padding_callback_arg() and SSL_get_record_padding_callback_arg() retrieve the arg value that's passed to the callback 🫶

Now for the block padding girlies: SSL_CTX_set_block_padding() and SSL_set_block_padding() pad the record to a multiple of block_size. A block_size of 0 or 1 disables block padding entirely. The limit of block_size is SSL3_RT_MAX_PLAIN_LENGTH — so don't try to go over that, it's giving "too much" energy 😭

And then there's SSL_CTX_set_block_padding_ex() and SSL_set_block_padding_ex() — they do basically the same thing but let you separately specify the padding block size for handshake and application data messages. So you can be like "this much for handshake, this much for app data" and it's lowkey iconic ✨

The callback gets invoked for every record before encryption. The type parameter is the TLS record type being processed — it can 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. And the arg parameter is the value set via SSL_CTX_set_record_padding_callback_arg() or SSL_set_record_padding_callback_arg().

Warning bestie: 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. So if you're on QUIC, this is not the vibe 💅

💖 RETURN VALUES 💖

The SSL_CTX_get_record_padding_callback_arg() and SSL_get_record_padding_callback_arg() functions return the arg value assigned in the corresponding set functions.

The SSL_CTX_set_block_padding() and SSL_set_block_padding() functions return 1 on success or 0 if block_size is too large.

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.

And wait, there's this one: The SSL_CTX_get_record_padding_callback_arg() function returns 1 on success or 0 if the callback function is not set because Kernel TLS is configured for the SSL object. Yeah, that's what it says — I'm not making this up, I promise 😭

🎀 NOTES 🎀

The default behavior is to add no padding to the record. So if you don't do anything, your records are just raw and unpadded, periodt.

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 you can always go back to the block padding vibe if you change your mind 💅

These functions only apply to TLS 1.3 records being written. So if you're on an older version, this whole page is not your moment, sorry bestie.

Also important: Padding bytes are not added in constant-time. So don't rely on this for timing side-channel protection — it's giving "aesthetic padding" not "security padding" 🙈

🌈 SEE ALSO 🌈

👑 HISTORY 👑

The record padding API was added for TLS 1.3 support in OpenSSL 1.1.1.

The return type of the SSL_CTX_set_record_padding_callback() function was changed to int in OpenSSL 3.0. (Yeah, the synopsis says void but history says int — I don't make the rules, I just report them 😭)

The functions SSL_set_block_padding_ex() and SSL_CTX_set_block_padding_ex() were added in OpenSSL 3.4. So they're the new kids on the block, literally.

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 whole page bestie 💖 This was literally OpenSSL 3.5.6, dated 2026-04-0 (yes, the date looks a little sus with that trailing zero, but that's what the footer says — I don't question the footer, I just report it 💀). Stay padded, stay slay ✨🎀🦋

📦 where this page comes from