SSL_CTX_SET_...DING_CALLBACK(3ossl)

💅 SSL_CTX_SET_...DING_CALLBACK — the OpenSSL fam (manual section 3ossl)

okay bestie, sit down, grab a boba, because we're talking about TLS 1.3 record padding and honestly? it's giving ✨control freak in the best way✨. this is the <openssl/ssl.h> girlies.

---

🌸 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 a callback to specify TLS 1.3 record padding 🎀

---

✨ 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 🦋

so SSL_CTX_set_record_padding_callback() and SSL_set_record_padding_callback() let you hand over a callback function cb that decides the padding for your TLS 1.3 records. main character energy, truly. the value you set on ctx gets copied into a new SSL by SSL_new() 🫶

⚠️ heads up: Kernel TLS is not possible if the record padding callback is set, and you also can't set the callback function if Kernel TLS is already configured for the current SSL object. pick a lane bestie, you cannot have both 💀

SSL_CTX_set_record_padding_callback_arg() and SSL_set_record_padding_callback_arg() assign a value arg that gets passed to the callback whenever it's invoked. and yes, the value set in ctx is copied to a new SSL by SSL_new() too. consistency queen 👑

SSL_CTX_get_record_padding_callback_arg() and SSL_get_record_padding_callback_arg() retrieve that arg value that's passed to the callback. getters, we love to see it.

SSL_CTX_set_block_padding() and SSL_set_block_padding() pad the record up to a multiple of block_size. a block_size of 0 or 1 disables block padding (so unserious). the limit of block_size is SSL3_RT_MAX_PLAIN_LENGTH.

SSL_CTX_set_block_padding_ex() and SSL_set_block_padding_ex() do the same lil thing but let the caller separately specify the padding block size to apply to handshake messages and to application data messages. fancy 💅

okay now the callback deets, because this is where it gets good:

• the callback is invoked for every record before encryption
• type — the TLS record type being processed; it may be one of SSL3_RT_APPLICATION_DATA, SSL3_RT_HANDSHAKE, or SSL3_RT_ALERT
• len — the current plaintext length of the record before encryption
• arg — the value set via SSL_CTX_set_record_padding_callback_arg() or SSL_set_record_padding_callback_arg()

🚨 and now the buzzkill: 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. no QUIC for you, sorry babe 🙈

---

💖 RETURN VALUES 💖

SSL_CTX_get_record_padding_callback_arg() and SSL_get_record_padding_callback_arg() return the arg value you assigned in the corresponding set functions. straightforward, iconic.

SSL_CTX_set_block_padding() and SSL_set_block_padding() return 1 on success, or 0 if block_size is too large. (rude, but okay.)

cb returns the number of padding bytes to add to the record. a return of 0 means no padding gets added — clean, minimal, no notes. and if your return value would make the record exceed the maximum record size (SSL3_RT_MAX_PLAIN_LENGTH), it'll pad out to the maximum record size instead. it simply will not let you overshoot 👑

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 that's what it says, keep it in your notes bestie 📝

---

🌈 NOTES 🌈

• the default behavior is to add no padding to the record. au naturel 🧚
• 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. it's giving toggles ✨
• these functions only apply to TLS 1.3 records being written. read that again. TLS 1.3. written. okay? 🫶
• > 💀 padding bytes are not added in constant-time. just so you know. that's a real caveat, not a vibe.

---

🔥 SEE ALSO 🔥

ssl(7), SSL_new(3)

---

⭐ HISTORY ⭐

• the record padding API was added for TLS 1.3 support in OpenSSL 1.1.1
• the return type of SSL_CTX_set_record_padding_callback() was changed to int in OpenSSL 3.0
• SSL_set_block_padding_ex() and SSL_CTX_set_block_padding_ex() were added in OpenSSL 3.4

---

👑 COPYRIGHT 👑

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 OpenSSL 3.5.9, dated 2026-09-2, section 3ossl — slay, stay padded, and remember: no constant-time, no QUIC, no cap ✨🎀🦋