1=pod
2
3=head1 NAME
4
5SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment,
6SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment,
7SSL_CTX_set_max_pipelines, SSL_set_max_pipelines,
8SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len,
9SSL_CTX_set_tlsext_max_fragment_length,
10SSL_set_tlsext_max_fragment_length,
11SSL_SESSION_get_max_fragment_length - Control fragment size settings and pipelining operations
12
13=head1 SYNOPSIS
14
15 #include <openssl/ssl.h>
16
17 long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long);
18 long SSL_set_max_send_fragment(SSL *ssl, long m);
19
20 long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m);
21 long SSL_set_max_pipelines(SSL_CTX *ssl, long m);
22
23 long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m);
24 long SSL_set_split_send_fragment(SSL *ssl, long m);
25
26 void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
27 void SSL_set_default_read_buffer_len(SSL *s, size_t len);
28
29 int SSL_CTX_set_tlsext_max_fragment_length(SSL_CTX *ctx, uint8_t mode);
30 int SSL_set_tlsext_max_fragment_length(SSL *ssl, uint8_t mode);
31 uint8_t SSL_SESSION_get_max_fragment_length(const SSL_SESSION *session);
32
33=head1 DESCRIPTION
34
35Some engines are able to process multiple simultaneous crypto operations. This
36capability could be utilised to parallelise the processing of a single
37connection. For example a single write can be split into multiple records and
38each one encrypted independently and in parallel. Note: this will only work in
39TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This
40capability is known as "pipelining" within OpenSSL.
41
42In order to benefit from the pipelining capability. You need to have an engine
43that provides ciphers that support this. The OpenSSL "dasync" engine provides
44AES128-SHA based ciphers that have this capability. However, these are for
45development and test purposes only.
46
47SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the
48B<max_send_fragment> parameter for SSL_CTX and SSL objects respectively. This
49value restricts the amount of plaintext bytes that will be sent in any one
50SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These
51functions will only accept a value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH.
52
53SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum number
54of pipelines that will be used at any one time. This value applies to both
55"read" pipelining and "write" pipelining. By default only one pipeline will be
56used (i.e. normal non-parallel operation). The number of pipelines set must be
57in the range 1 - SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also
58automatically turn on "read_ahead" (see L<SSL_CTX_set_read_ahead(3)>). This is
59explained further below. OpenSSL will only ever use more than one pipeline if
60a cipher suite is negotiated that uses a pipeline capable cipher provided by an
61engine.
62
63Pipelining operates slightly differently for reading encrypted data compared to
64writing encrypted data. SSL_CTX_set_split_send_fragment() and
65SSL_set_split_send_fragment() define how data is split up into pipelines when
66writing encrypted data. The number of pipelines used will be determined by the
67amount of data provided to the SSL_write_ex() or SSL_write() call divided by
68B<split_send_fragment>.
69
70For example if B<split_send_fragment> is set to 2000 and B<max_pipelines> is 4
71then:
72
73SSL_write/SSL_write_ex called with 0-2000 bytes == 1 pipeline used
74
75SSL_write/SSL_write_ex called with 2001-4000 bytes == 2 pipelines used
76
77SSL_write/SSL_write_ex called with 4001-6000 bytes == 3 pipelines used
78
79SSL_write/SSL_write_ex called with 6001+ bytes == 4 pipelines used
80
81B<split_send_fragment> must always be less than or equal to
82B<max_send_fragment>. By default it is set to be equal to B<max_send_fragment>.
83This will mean that the same number of records will always be created as would
84have been created in the non-parallel case, although the data will be
85apportioned differently. In the parallel case data will be spread equally
86between the pipelines.
87
88Read pipelining is controlled in a slightly different way than with write
89pipelining. While reading we are constrained by the number of records that the
90peer (and the network) can provide to us in one go. The more records we can get
91in one go the more opportunity we have to parallelise the processing. As noted
92above when setting B<max_pipelines> to a value greater than one, B<read_ahead>
93is automatically set. The B<read_ahead> parameter causes OpenSSL to attempt to
94read as much data into the read buffer as the network can provide and will fit
95into the buffer. Without this set data is read into the read buffer one record
96at a time. The more data that can be read, the more opportunity there is for
97parallelising the processing at the cost of increased memory overhead per
98connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending()
99function (see L<SSL_pending(3)>). In addition the default size of the internal
100read buffer is multiplied by the number of pipelines available to ensure that we
101can read multiple records in one go. This can therefore have a significant
102impact on memory usage.
103
104The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
105functions control the size of the read buffer that will be used. The B<len>
106parameter sets the size of the buffer. The value will only be used if it is
107greater than the default that would have been used anyway. The normal default
108value depends on a number of factors but it will be at least
109SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes.
110
111SSL_CTX_set_tlsext_max_fragment_length() sets the default maximum fragment
112length negotiation mode via value B<mode> to B<ctx>.
113This setting affects only SSL instances created after this function is called.
114It affects the client-side as only its side may initiate this extension use.
115
116SSL_set_tlsext_max_fragment_length() sets the maximum fragment length
117negotiation mode via value B<mode> to B<ssl>.
118This setting will be used during a handshake when extensions are exchanged
119between client and server.
120So it only affects SSL sessions created after this function is called.
121It affects the client-side as only its side may initiate this extension use.
122
123SSL_SESSION_get_max_fragment_length() gets the maximum fragment length
124negotiated in B<session>.
125
126These functions cannot be used with QUIC SSL objects.
127SSL_set_max_send_fragment(), SSL_set_max_pipelines(),
128SSL_set_split_send_fragment(), SSL_set_default_read_buffer_len() and
129SSL_set_tlsext_max_fragment_length() fail if called on a QUIC SSL object.
130
131=head1 RETURN VALUES
132
133All non-void functions return 1 on success and 0 on failure.
134
135=head1 NOTES
136
137The Maximum Fragment Length extension support is optional on the server side.
138If the server does not support this extension then
139SSL_SESSION_get_max_fragment_length() will return:
140TLSEXT_max_fragment_length_DISABLED.
141
142The following modes are available:
143
144=over 4
145
146=item TLSEXT_max_fragment_length_DISABLED
147
148Disables Maximum Fragment Length Negotiation (default).
149
150=item TLSEXT_max_fragment_length_512
151
152Sets Maximum Fragment Length to 512 bytes.
153
154=item TLSEXT_max_fragment_length_1024
155
156Sets Maximum Fragment Length to 1024.
157
158=item TLSEXT_max_fragment_length_2048
159
160Sets Maximum Fragment Length to 2048.
161
162=item TLSEXT_max_fragment_length_4096
163
164Sets Maximum Fragment Length to 4096.
165
166=back
167
168With the exception of SSL_CTX_set_default_read_buffer_len()
169SSL_set_default_read_buffer_len(), SSL_CTX_set_tlsext_max_fragment_length(),
170SSL_set_tlsext_max_fragment_length() and SSL_SESSION_get_max_fragment_length()
171all these functions are implemented using macros.
172
173=head1 SEE ALSO
174
175L<ssl(7)>,
176L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>
177
178=head1 HISTORY
179
180The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(),
181SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(),
182SSL_CTX_set_default_read_buffer_len() and  SSL_set_default_read_buffer_len()
183functions were added in OpenSSL 1.1.0.
184
185The SSL_CTX_set_tlsext_max_fragment_length(), SSL_set_tlsext_max_fragment_length()
186and SSL_SESSION_get_max_fragment_length() functions were added in OpenSSL 1.1.1.
187
188=head1 COPYRIGHT
189
190Copyright 2016-2023 The OpenSSL Project Authors. All Rights Reserved.
191
192Licensed under the Apache License 2.0 (the "License").  You may not use
193this file except in compliance with the License.  You can obtain a copy
194in the file LICENSE in the source distribution or at
195L<https://www.openssl.org/source/license.html>.
196
197=cut
198