SSL_CTX_SET_...DING_CALLBACK(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

🌸 SSL_CTX_SET_...DING_CALLBACK ✨

okay bestie, sit DOWN, because this one is from the OpenSSL 3SSL manual and it's all about installing a callback to specify TLS 1.3 record padding 💅 like. we're customizing how many lil extra bytes get tacked onto your records before encryption. so cute. so powerful. let's go 🫶

The star-studded cast, in alphabetical-ish order (yes, all of them, I would never leave one out, that's not the vibe):

  • 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

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

like look at those signatures bestie, gorgeous, immaculate, no notes 😌

🦋 DESCRIPTION 🦋

so SSL_CTX_set_record_padding_callback() and SSL_set_record_padding_callback() are how you hand over a callback function cb that decides the padding for TLS 1.3 records. the value you set in ctx? it gets copied into a brand-new SSL by SSL_new(). 💖

⚠️ okay important: 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 "pick one, babe" 💀

Then SSL_CTX_set_record_padding_callback_arg() and SSL_set_record_padding_callback_arg() assign a value arg that gets passed straight to the callback whenever it's invoked. and yep — the value set in ctx is copied to a new SSL by SSL_new(). ✨

SSL_CTX_get_record_padding_callback_arg() and SSL_get_record_padding_callback_arg() fetch back that arg value you handed to the callback. retrieval arc 🎀

Now for the block padding girlies:

  • SSL_CTX_set_block_padding() and SSL_set_block_padding() pad the record out to a multiple of the block_size. a block_size of 0 or 1 disables block padding (yes really). and the limit of block_size is SSL3_RT_MAX_PLAIN_LENGTH. 📏
  • SSL_CTX_set_block_padding_ex() and SSL_set_block_padding_ex() do basically the same thing but let you separately specify the padding block size that gets applied to handshake vs application data messages. main character energy, honestly 👑

💫 the callback, deconstructed 💫

the callback fires for every record before encryption. here's the tea on its parameters:

  • 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 you set via SSL_CTX_set_record_padding_callback_arg() or SSL_set_record_padding_callback_arg().

🚫 QUIC girlies, this is not for you 🚫

These functions cannot be used with QUIC SSL objects. and to be extra clear: SSL_set_record_padding_callback() and SSL_set_block_padding() fail if called on a QUIC SSL object. 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. periodt.
  • SSL_CTX_set_block_padding() and SSL_set_block_padding() return 1 on success, or 0 if block_size is too large. (too much?? too much. 🫠)
  • cb returns the number of padding bytes to add to the record. a return of 0 means no padding will be added. and a return value that would push the record past the maximum record size (SSL3_RT_MAX_PLAIN_LENGTH)? it'll just pad out to the maximum record size instead. iconic, honestly, it self-corrects 💅
  • SSL_CTX_get_record_padding_callback_arg() — okay this one's a little ✨special✨ in the docs — returns 1 on success, or 0 if the callback function is not set because Kernel TLS is configured for the SSL object. yes, 1. I know. I'm just telling you what the page says, bestie 😭

🎀 NOTES 🎀

  • the default behavior is to add no padding to the record. chill. minimal. a little mysterious ✨
  • a user-supplied padding callback function will override the behavior set by SSL_set_block_padding() or SSL_CTX_set_block_padding(). and setting the user-supplied callback to NULL restores the configured block padding behavior. so you can always take it back 🥰
  • These functions only apply to TLS 1.3 records being written. not reading. writing. only. 📝
  • Padding bytes are not added in constant-time. 👀 clock that, it's a real caveat

👑 SEE ALSO 👑

ssl(7), SSL_new(3) — go read those too, they're also good, I don't make the rules 🫶

⭐ 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() function was changed to int in OpenSSL 3.0.
  • The functions SSL_set_block_padding_ex() and SSL_CTX_set_block_padding_ex() were added in OpenSSL 3.4. fresh drops 🔥

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 one's from OpenSSL version 4.0.3, dated 2026-09-29 — go forth and pad your records responsibly, ily, mwah 💋🌈🦋✨

📦 where this page comes from