1SSL_CTX_SET_SPLIT_SEND_FRAGMENT(3)  OpenSSL SSL_CTX_SET_SPLIT_SEND_FRAGMENT(3)
2
3
4

NAME

6       SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment,
7       SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment,
8       SSL_CTX_set_max_pipelines, SSL_set_max_pipelines,
9       SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len,
10       SSL_CTX_set_tlsext_max_fragment_length,
11       SSL_set_tlsext_max_fragment_length, SSL_SESSION_get_max_fragment_length
12       - Control fragment size settings and pipelining operations
13

SYNOPSIS

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(SSL_SESSION *session);
32

DESCRIPTION

34       Some engines are able to process multiple simultaneous crypto
35       operations. This capability could be utilised to parallelise the
36       processing of a single connection. For example a single write can be
37       split into multiple records and each one encrypted independently and in
38       parallel. Note: this will only work in TLS1.1+. There is no support in
39       SSLv3, TLSv1.0 or DTLS (any version). This capability is known as
40       "pipelining" within OpenSSL.
41
42       In order to benefit from the pipelining capability. You need to have an
43       engine that provides ciphers that support this. The OpenSSL "dasync"
44       engine provides AES128-SHA based ciphers that have this capability.
45       However, these are for development and test purposes only.
46
47       SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the
48       max_send_fragment parameter for SSL_CTX and SSL objects respectively.
49       This value restricts the amount of plaintext bytes that will be sent in
50       any one SSL/TLS record. By default its value is
51       SSL3_RT_MAX_PLAIN_LENGTH (16384). These functions will only accept a
52       value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH.
53
54       SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum
55       number of pipelines that will be used at any one time. This value
56       applies to both "read" pipelining and "write" pipelining. By default
57       only one pipeline will be used (i.e. normal non-parallel operation).
58       The number of pipelines set must be in the range 1 - SSL_MAX_PIPELINES
59       (32). Setting this to a value > 1 will also automatically turn on
60       "read_ahead" (see SSL_CTX_set_read_ahead(3)). This is explained further
61       below. OpenSSL will only every use more than one pipeline if a cipher
62       suite is negotiated that uses a pipeline capable cipher provided by an
63       engine.
64
65       Pipelining operates slightly differently for reading encrypted data
66       compared to writing encrypted data. SSL_CTX_set_split_send_fragment()
67       and SSL_set_split_send_fragment() define how data is split up into
68       pipelines when writing encrypted data. The number of pipelines used
69       will be determined by the amount of data provided to the SSL_write_ex()
70       or SSL_write() call divided by split_send_fragment.
71
72       For example if split_send_fragment is set to 2000 and max_pipelines is
73       4 then:
74
75       SSL_write/SSL_write_ex called with 0-2000 bytes == 1 pipeline used
76
77       SSL_write/SSL_write_ex called with 2001-4000 bytes == 2 pipelines used
78
79       SSL_write/SSL_write_ex called with 4001-6000 bytes == 3 pipelines used
80
81       SSL_write/SSL_write_ex called with 6001+ bytes == 4 pipelines used
82
83       split_send_fragment must always be less than or equal to
84       max_send_fragment. By default it is set to be equal to
85       max_send_fragment.  This will mean that the same number of records will
86       always be created as would have been created in the non-parallel case,
87       although the data will be apportioned differently. In the parallel case
88       data will be spread equally between the pipelines.
89
90       Read pipelining is controlled in a slightly different way than with
91       write pipelining. While reading we are constrained by the number of
92       records that the peer (and the network) can provide to us in one go.
93       The more records we can get in one go the more opportunity we have to
94       parallelise the processing. As noted above when setting max_pipelines
95       to a value greater than one, read_ahead is automatically set. The
96       read_ahead parameter causes OpenSSL to attempt to read as much data
97       into the read buffer as the network can provide and will fit into the
98       buffer. Without this set data is read into the read buffer one record
99       at a time. The more data that can be read, the more opportunity there
100       is for parallelising the processing at the cost of increased memory
101       overhead per connection. Setting read_ahead can impact the behaviour of
102       the SSL_pending() function (see SSL_pending(3)).
103
104       The SSL_CTX_set_default_read_buffer_len() and
105       SSL_set_default_read_buffer_len() functions control the size of the
106       read buffer that will be used. The len parameter sets the size of the
107       buffer. The value will only be used if it is greater than the default
108       that would have been used anyway. The normal default value depends on a
109       number of factors but it will be at least SSL3_RT_MAX_PLAIN_LENGTH +
110       SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes.
111
112       SSL_CTX_set_tlsext_max_fragment_length() sets the default maximum
113       fragment length negotiation mode via value mode to ctx.  This setting
114       affects only SSL instances created after this function is called.  It
115       affects the client-side as only its side may initiate this extension
116       use.
117
118       SSL_set_tlsext_max_fragment_length() sets the maximum fragment length
119       negotiation mode via value mode to ssl.  This setting will be used
120       during a handshake when extensions are exchanged between client and
121       server.  So it only affects SSL sessions created after this function is
122       called.  It affects the client-side as only its side may initiate this
123       extension use.
124
125       SSL_SESSION_get_max_fragment_length() gets the maximum fragment length
126       negotiated in session.
127

RETURN VALUES

129       All non-void functions return 1 on success and 0 on failure.
130

NOTES

132       The Maximum Fragment Length extension support is optional on the server
133       side.  If the server does not support this extension then
134       SSL_SESSION_get_max_fragment_length() will return:
135       TLSEXT_max_fragment_length_DISABLED.
136
137       The following modes are available:
138
139       TLSEXT_max_fragment_length_DISABLED
140           Disables Maximum Fragment Length Negotiation (default).
141
142       TLSEXT_max_fragment_length_512
143           Sets Maximum Fragment Length to 512 bytes.
144
145       TLSEXT_max_fragment_length_1024
146           Sets Maximum Fragment Length to 1024.
147
148       TLSEXT_max_fragment_length_2048
149           Sets Maximum Fragment Length to 2048.
150
151       TLSEXT_max_fragment_length_4096
152           Sets Maximum Fragment Length to 4096.
153
154       With the exception of SSL_CTX_set_default_read_buffer_len()
155       SSL_set_default_read_buffer_len(),
156       SSL_CTX_set_tlsext_max_fragment_length(),
157       SSL_set_tlsext_max_fragment_length() and
158       SSL_SESSION_get_max_fragment_length() all these functions are
159       implemented using macros.
160

SEE ALSO

162       SSL_CTX_set_read_ahead(3), SSL_pending(3)
163

HISTORY

165       The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(),
166       SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(),
167       SSL_CTX_set_default_read_buffer_len() and
168       SSL_set_default_read_buffer_len() functions were added in OpenSSL
169       1.1.0.
170
171       The SSL_CTX_set_tlsext_max_fragment_length(),
172       SSL_set_tlsext_max_fragment_length() and
173       SSL_SESSION_get_max_fragment_length() functions were added in OpenSSL
174       1.1.1.
175
177       Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
178
179       Licensed under the OpenSSL license (the "License").  You may not use
180       this file except in compliance with the License.  You can obtain a copy
181       in the file LICENSE in the source distribution or at
182       <https://www.openssl.org/source/license.html>.
183
184
185
1861.1.1k                            2021-03-26SSL_CTX_SET_SPLIT_SEND_FRAGMENT(3)
Impressum