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