SSL_CTX_SET_...SEND_FRAGMENT(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

💖 SSL_CTX_SET_...SEND_FRAGMENT(3SSL) 💖

okay bestie, gather round, because this is the SSL_CTX_SET_...SEND_FRAGMENT(3SSL) page from the OpenSSL manual and it's lowkey a whole saga about fragment sizes, pipelines, and read buffers. it's giving "networking internals but make it cute". let's go 🦋

✨ NAME ✨

so basically this page covers a whole friend group of functions:

  • SSL_CTX_set_max_send_fragment
  • SSL_set_max_send_fragment
  • SSL_CTX_set_split_send_fragment
  • SSL_set_split_send_fragment
  • SSL_CTX_set_max_pipelines
  • SSL_set_max_pipelines
  • SSL_CTX_set_default_read_buffer_len
  • SSL_set_default_read_buffer_len
  • SSL_CTX_set_tlsext_max_fragment_length
  • SSL_set_tlsext_max_fragment_length
  • SSL_SESSION_get_max_fragment_length

and what do they all do? they control fragment size settings and pipelining operations. iconic, honestly. 👑

🌸 SYNOPSIS 🌸

#include <openssl/ssl.h>

long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long);
long SSL_set_max_send_fragment(SSL *ssl, long m);

long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m);
long SSL_set_max_pipelines(SSL *ssl, long m);

long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m);
long SSL_set_split_send_fragment(SSL *ssl, long m);

void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
void SSL_set_default_read_buffer_len(SSL *s, size_t len);

int SSL_CTX_set_tlsext_max_fragment_length(SSL_CTX *ctx, uint8_t mode);
int SSL_set_tlsext_max_fragment_length(SSL *ssl, uint8_t mode);
uint8_t SSL_SESSION_get_max_fragment_length(const SSL_SESSION *session);

no cap, that's the whole roster. 💅

🎀 DESCRIPTION 🎀

🧚 the pipelining lore (rip boo, you would've loved her)

so. previous versions of libssl supported the concept of cipher pipelining. there is no support for this in OpenSSL 4.0. periodt. 💀

back in the day, some engines were able to process multiple simultaneous crypto operations. this capability could be utilised to parallelise the processing of a single connection. for example, a single write can be split into multiple records and each one encrypted independently and in parallel.

⚠️ note: this would only work in TLS1.1+. there was no support in SSLv3, TLSv1.0 or DTLS (any version). this capability is known as "pipelining" within OpenSSL.

in order to benefit from the pipelining capability, you would need to have an engine that provides ciphers that support this. since OpenSSL 4.0, engines are no longer supported and therefore pipelining is not supported either. in some future version it may be that this capability is added back via the provider mechanism. so like… watch this space, bestie. 🙈

📏 max send fragment stuff

SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the max_send_fragment parameter for SSL_CTX and SSL objects respectively. this value restricts the amount of plaintext bytes that will be sent in any one SSL/TLS record.

by default its value is SSL3_RT_MAX_PLAIN_LENGTH which is 16384. these functions will only accept a value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH. so don't try anything funny. ✨

🔥 max pipelines (the parallelisation queen, RIP)

SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum number of pipelines that will be used at any one time. this value applies to both "read" pipelining and "write" pipelining.

by default only one pipeline will be used (i.e. normal non-parallel operation). the number of pipelines set must be in the range 1 - SSL_MAX_PIPELINES (32).

setting this to a value > 1 will also automatically turn on "read_ahead" (see SSL_CTX_set_read_ahead(3)). this is explained further below. OpenSSL will only ever use more than one pipeline if a cipher suite is negotiated that uses a pipeline capable cipher provided by an engine. so like, it takes two to tango. 💃

✂️ split send fragment (the write-side arrangement)

pipelining operates slightly differently for reading encrypted data compared to writing encrypted data. SSL_CTX_set_split_send_fragment() and SSL_set_split_send_fragment() define how data is split up into pipelines when writing encrypted data. the number of pipelines used will be determined by the amount of data provided to the SSL_write_ex() or SSL_write() call divided by split_send_fragment.

for example, if split_send_fragment is set to 2000 and max_pipelines is 4 then:

  • SSL_write/SSL_write_ex called with 0-2000 bytes == 1 pipeline used
  • SSL_write/SSL_write_ex called with 2001-4000 bytes == 2 pipelines used
  • SSL_write/SSL_write_ex called with 4001-6000 bytes == 3 pipelines used
  • SSL_write/SSL_write_ex called with 6001+ bytes == 4 pipelines used

split_send_fragment must always be less than or equal to max_send_fragment. by default it is set to be equal to max_send_fragment. this will mean that the same number of records will always be created as would have been created in the non-parallel case, although the data will be apportioned differently. in the parallel case, data will be spread equally between the pipelines. balanced, as all things should be. 🫶

👀 read pipelining (the messy one)

read pipelining is controlled in a slightly different way than with write pipelining. while reading we are constrained by the number of records that the peer (and the network) can provide to us in one go. the more records we can get in one go, the more opportunity we have to parallelise the processing.

as noted above, when setting max_pipelines to a value greater than one, read_ahead is automatically set. the read_ahead parameter causes OpenSSL to attempt to read as much data into the read buffer as the network can provide and will fit into the buffer. without this set, data is read into the read buffer one record at a time. the more data that can be read, the more opportunity there is for parallelising the processing — at the cost of increased memory overhead per connection.

⚠️ heads up bestie: setting read_ahead can impact the behaviour of the SSL_pending() function (see SSL_pending(3)). in addition, the default size of the internal read buffer is multiplied by the number of pipelines available to ensure that we can read multiple records in one go. this can therefore have a significant impact on memory usage. not me warning you about your RAM… 😭

🧺 default read buffer len

the SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len() functions control the size of the read buffer that will be used. the len parameter sets the size of the buffer.

the value will only be used if it is greater than the default that would have been used anyway. the normal default value depends on a number of factors but it will be at least SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes. so like, 16704 is the floor, bestie. 🍓

🌈 tlsext max fragment length functions

SSL_CTX_set_tlsext_max_fragment_length() sets the default maximum fragment length negotiation mode via value mode to ctx. this setting affects only SSL instances created after this function is called. it affects the client-side, as only its side may initiate this extension use.

SSL_set_tlsext_max_fragment_length() sets the maximum fragment length negotiation mode via value mode to ssl. this setting will be used during a handshake when extensions are exchanged between client and server. so it only affects SSL sessions created after this function is called. it affects the client-side, as only its side may initiate this extension use.

SSL_SESSION_get_max_fragment_length() gets the maximum fragment length negotiated in session.

💀 the QUIC situation

these functions cannot be used with QUIC SSL objects.

SSL_set_max_send_fragment(), SSL_set_max_pipelines(), SSL_set_split_send_fragment(), SSL_set_default_read_buffer_len() and SSL_set_tlsext_max_fragment_length() fail if called on a QUIC SSL object. like, they will simply not be doing that. nope. 🙅

⭐ RETURN VALUES ⭐

all non-void functions return 1 on success and 0 on failure. binary queen behaviour. 💅

👑 NOTES 👑

the Maximum Fragment Length extension support is optional on the server side. if the server does not support this extension then SSL_SESSION_get_max_fragment_length() will return: TLSEXT_max_fragment_length_DISABLED.

the following modes are available:

  • TLSEXT_max_fragment_length_DISABLED — disables Maximum Fragment Length Negotiation (default).
  • TLSEXT_max_fragment_length_512 — sets Maximum Fragment Length to 512 bytes.
  • TLSEXT_max_fragment_length_1024 — sets Maximum Fragment Length to 1024.
  • TLSEXT_max_fragment_length_2048 — sets Maximum Fragment Length to 2048.
  • TLSEXT_max_fragment_length_4096 — sets Maximum Fragment Length to 4096.

and here's the fun lil implementation tea ☕ — with the exception of SSL_CTX_set_default_read_buffer_len(), SSL_set_default_read_buffer_len(), SSL_CTX_set_tlsext_max_fragment_length(), SSL_set_tlsext_max_fragment_length() and SSL_SESSION_get_max_fragment_length(), all these functions are implemented using macros. iykyk. ✨

🔗 SEE ALSO 🔗

ssl(7), SSL_CTX_set_read_ahead(3), SSL_pending(3)

go read those next, bestie, they're literally the supporting cast. 🎀

🦋 HISTORY 🦋

the SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(), SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(), SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len() functions were added in OpenSSL 1.1.0.

the SSL_CTX_set_tlsext_max_fragment_length(), SSL_set_tlsext_max_fragment_length() and SSL_SESSION_get_max_fragment_length() functions were added in OpenSSL 1.1.1.

we been knew. 💜

Copyright 2016-2025 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 SSL_CTX_SET_...SEND_FRAGMENT(3SSL) from OpenSSL version 4.0.3, dated 2026-09-29. slay, go forth and set your fragment sizes responsibly. mwah 💋✨

📦 where this page comes from