Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_split_send_fragment.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CTX_SET_SPLIT_SEND_FRAGMENT 3SSL"
58 .TH SSL_CTX_SET_SPLIT_SEND_FRAGMENT 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment,
65 SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment,
66 SSL_CTX_set_max_pipelines, SSL_set_max_pipelines,
67 SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len,
68 SSL_CTX_set_tlsext_max_fragment_length,
69 SSL_set_tlsext_max_fragment_length,
70 SSL_SESSION_get_max_fragment_length \- Control fragment size settings and pipelining operations
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 1
74 \& #include <openssl/ssl.h>
75 \&
76 \& long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long);
77 \& long SSL_set_max_send_fragment(SSL *ssl, long m);
78 \&
79 \& long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m);
80 \& long SSL_set_max_pipelines(SSL_CTX *ssl, long m);
81 \&
82 \& long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m);
83 \& long SSL_set_split_send_fragment(SSL *ssl, long m);
84 \&
85 \& void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
86 \& void SSL_set_default_read_buffer_len(SSL *s, size_t len);
87 \&
88 \& int SSL_CTX_set_tlsext_max_fragment_length(SSL_CTX *ctx, uint8_t mode);
89 \& int SSL_set_tlsext_max_fragment_length(SSL *ssl, uint8_t mode);
90 \& uint8_t SSL_SESSION_get_max_fragment_length(const SSL_SESSION *session);
91 .Ve
92 .SH DESCRIPTION
93 .IX Header "DESCRIPTION"
94 Some engines are able to process multiple simultaneous crypto operations. This
95 capability could be utilised to parallelise the processing of a single
96 connection. For example a single write can be split into multiple records and
97 each one encrypted independently and in parallel. Note: this will only work in
98 TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This
99 capability is known as "pipelining" within OpenSSL.
100 .PP
101 In order to benefit from the pipelining capability. You need to have an engine
102 that provides ciphers that support this. The OpenSSL "dasync" engine provides
103 AES128\-SHA based ciphers that have this capability. However, these are for
104 development and test purposes only.
105 .PP
106 \&\fBSSL_CTX_set_max_send_fragment()\fR and \fBSSL_set_max_send_fragment()\fR set the
107 \&\fBmax_send_fragment\fR parameter for SSL_CTX and SSL objects respectively. This
108 value restricts the amount of plaintext bytes that will be sent in any one
109 SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These
110 functions will only accept a value in the range 512 \- SSL3_RT_MAX_PLAIN_LENGTH.
111 .PP
112 \&\fBSSL_CTX_set_max_pipelines()\fR and \fBSSL_set_max_pipelines()\fR set the maximum number
113 of pipelines that will be used at any one time. This value applies to both
114 "read" pipelining and "write" pipelining. By default only one pipeline will be
115 used (i.e. normal non-parallel operation). The number of pipelines set must be
116 in the range 1 \- SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also
117 automatically turn on "read_ahead" (see \fBSSL_CTX_set_read_ahead\fR\|(3)). This is
118 explained further below. OpenSSL will only ever use more than one pipeline if
119 a cipher suite is negotiated that uses a pipeline capable cipher provided by an
120 engine.
121 .PP
122 Pipelining operates slightly differently for reading encrypted data compared to
123 writing encrypted data. \fBSSL_CTX_set_split_send_fragment()\fR and
124 \&\fBSSL_set_split_send_fragment()\fR define how data is split up into pipelines when
125 writing encrypted data. The number of pipelines used will be determined by the
126 amount of data provided to the \fBSSL_write_ex()\fR or \fBSSL_write()\fR call divided by
127 \&\fBsplit_send_fragment\fR.
128 .PP
129 For example if \fBsplit_send_fragment\fR is set to 2000 and \fBmax_pipelines\fR is 4
130 then:
131 .PP
132 SSL_write/SSL_write_ex called with 0\-2000 bytes == 1 pipeline used
133 .PP
134 SSL_write/SSL_write_ex called with 2001\-4000 bytes == 2 pipelines used
135 .PP
136 SSL_write/SSL_write_ex called with 4001\-6000 bytes == 3 pipelines used
137 .PP
138 SSL_write/SSL_write_ex called with 6001+ bytes == 4 pipelines used
139 .PP
140 \&\fBsplit_send_fragment\fR must always be less than or equal to
141 \&\fBmax_send_fragment\fR. By default it is set to be equal to \fBmax_send_fragment\fR.
142 This will mean that the same number of records will always be created as would
143 have been created in the non-parallel case, although the data will be
144 apportioned differently. In the parallel case data will be spread equally
145 between the pipelines.
146 .PP
147 Read pipelining is controlled in a slightly different way than with write
148 pipelining. While reading we are constrained by the number of records that the
149 peer (and the network) can provide to us in one go. The more records we can get
150 in one go the more opportunity we have to parallelise the processing. As noted
151 above when setting \fBmax_pipelines\fR to a value greater than one, \fBread_ahead\fR
152 is automatically set. The \fBread_ahead\fR parameter causes OpenSSL to attempt to
153 read as much data into the read buffer as the network can provide and will fit
154 into the buffer. Without this set data is read into the read buffer one record
155 at a time. The more data that can be read, the more opportunity there is for
156 parallelising the processing at the cost of increased memory overhead per
157 connection. Setting \fBread_ahead\fR can impact the behaviour of the \fBSSL_pending()\fR
158 function (see \fBSSL_pending\fR\|(3)). In addition the default size of the internal
159 read buffer is multiplied by the number of pipelines available to ensure that we
160 can read multiple records in one go. This can therefore have a significant
161 impact on memory usage.
162 .PP
163 The \fBSSL_CTX_set_default_read_buffer_len()\fR and \fBSSL_set_default_read_buffer_len()\fR
164 functions control the size of the read buffer that will be used. The \fBlen\fR
165 parameter sets the size of the buffer. The value will only be used if it is
166 greater than the default that would have been used anyway. The normal default
167 value depends on a number of factors but it will be at least
168 SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes.
169 .PP
170 \&\fBSSL_CTX_set_tlsext_max_fragment_length()\fR sets the default maximum fragment
171 length negotiation mode via value \fBmode\fR to \fBctx\fR.
172 This setting affects only SSL instances created after this function is called.
173 It affects the client-side as only its side may initiate this extension use.
174 .PP
175 \&\fBSSL_set_tlsext_max_fragment_length()\fR sets the maximum fragment length
176 negotiation mode via value \fBmode\fR to \fBssl\fR.
177 This setting will be used during a handshake when extensions are exchanged
178 between client and server.
179 So it only affects SSL sessions created after this function is called.
180 It affects the client-side as only its side may initiate this extension use.
181 .PP
182 \&\fBSSL_SESSION_get_max_fragment_length()\fR gets the maximum fragment length
183 negotiated in \fBsession\fR.
184 .PP
185 These functions cannot be used with QUIC SSL objects.
186 \&\fBSSL_set_max_send_fragment()\fR, \fBSSL_set_max_pipelines()\fR,
187 \&\fBSSL_set_split_send_fragment()\fR, \fBSSL_set_default_read_buffer_len()\fR and
188 \&\fBSSL_set_tlsext_max_fragment_length()\fR fail if called on a QUIC SSL object.
189 .SH "RETURN VALUES"
190 .IX Header "RETURN VALUES"
191 All non-void functions return 1 on success and 0 on failure.
192 .SH NOTES
193 .IX Header "NOTES"
194 The Maximum Fragment Length extension support is optional on the server side.
195 If the server does not support this extension then
196 \&\fBSSL_SESSION_get_max_fragment_length()\fR will return:
197 TLSEXT_max_fragment_length_DISABLED.
198 .PP
199 The following modes are available:
200 .IP TLSEXT_max_fragment_length_DISABLED 4
201 .IX Item "TLSEXT_max_fragment_length_DISABLED"
202 Disables Maximum Fragment Length Negotiation (default).
203 .IP TLSEXT_max_fragment_length_512 4
204 .IX Item "TLSEXT_max_fragment_length_512"
205 Sets Maximum Fragment Length to 512 bytes.
206 .IP TLSEXT_max_fragment_length_1024 4
207 .IX Item "TLSEXT_max_fragment_length_1024"
208 Sets Maximum Fragment Length to 1024.
209 .IP TLSEXT_max_fragment_length_2048 4
210 .IX Item "TLSEXT_max_fragment_length_2048"
211 Sets Maximum Fragment Length to 2048.
212 .IP TLSEXT_max_fragment_length_4096 4
213 .IX Item "TLSEXT_max_fragment_length_4096"
214 Sets Maximum Fragment Length to 4096.
215 .PP
216 With the exception of \fBSSL_CTX_set_default_read_buffer_len()\fR
217 \&\fBSSL_set_default_read_buffer_len()\fR, \fBSSL_CTX_set_tlsext_max_fragment_length()\fR,
218 \&\fBSSL_set_tlsext_max_fragment_length()\fR and \fBSSL_SESSION_get_max_fragment_length()\fR
219 all these functions are implemented using macros.
220 .SH "SEE ALSO"
221 .IX Header "SEE ALSO"
222 \&\fBssl\fR\|(7),
223 \&\fBSSL_CTX_set_read_ahead\fR\|(3), \fBSSL_pending\fR\|(3)
224 .SH HISTORY
225 .IX Header "HISTORY"
226 The \fBSSL_CTX_set_max_pipelines()\fR, \fBSSL_set_max_pipelines()\fR,
227 \&\fBSSL_CTX_set_split_send_fragment()\fR, \fBSSL_set_split_send_fragment()\fR,
228 \&\fBSSL_CTX_set_default_read_buffer_len()\fR and \fBSSL_set_default_read_buffer_len()\fR
229 functions were added in OpenSSL 1.1.0.
230 .PP
231 The \fBSSL_CTX_set_tlsext_max_fragment_length()\fR, \fBSSL_set_tlsext_max_fragment_length()\fR
232 and \fBSSL_SESSION_get_max_fragment_length()\fR functions were added in OpenSSL 1.1.1.
233 .SH COPYRIGHT
234 .IX Header "COPYRIGHT"
235 Copyright 2016\-2023 The OpenSSL Project Authors. All Rights Reserved.
236 .PP
237 Licensed under the Apache License 2.0 (the "License"). You may not use
238 this file except in compliance with the License. You can obtain a copy
239 in the file LICENSE in the source distribution or at
240 <https://www.openssl.org/source/license.html>.