]>
Commit | Line | Data |
---|---|---|
8061d964 MC |
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, | |
cf72c757 F |
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 | |
8061d964 MC |
12 | |
13 | =head1 SYNOPSIS | |
14 | ||
15 | #include <openssl/ssl.h> | |
16 | ||
91da5e77 RS |
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); | |
8061d964 MC |
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 | ||
cf72c757 F |
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 | ||
8061d964 MC |
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 | |
c4de074e | 60 | a cipher suite is negotiated that uses a pipeline capable cipher provided by an |
8061d964 MC |
61 | engine. |
62 | ||
24c2cd39 | 63 | Pipelining operates slightly differently for reading encrypted data compared to |
8061d964 MC |
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 | |
7714dc5e | 67 | amount of data provided to the SSL_write_ex() or SSL_write() call divided by |
8061d964 MC |
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 | ||
6782e5fd | 73 | SSL_write/SSL_write_ex called with 0-2000 bytes == 1 pipeline used |
8061d964 | 74 | |
6782e5fd | 75 | SSL_write/SSL_write_ex called with 2001-4000 bytes == 2 pipelines used |
8061d964 | 76 | |
6782e5fd | 77 | SSL_write/SSL_write_ex called with 4001-6000 bytes == 3 pipelines used |
8061d964 | 78 | |
6782e5fd | 79 | SSL_write/SSL_write_ex called with 6001+ bytes == 4 pipelines used |
8061d964 MC |
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 | |
d7ded13a MC |
98 | connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending() |
99 | function (see L<SSL_pending(3)>). | |
8061d964 MC |
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 | ||
cf72c757 F |
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 | ||
8061d964 MC |
123 | =head1 RETURN VALUES |
124 | ||
125 | All non-void functions return 1 on success and 0 on failure. | |
126 | ||
127 | =head1 NOTES | |
128 | ||
cf72c757 F |
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. | |
8061d964 | 164 | |
18bad535 JL |
165 | =head1 SEE ALSO |
166 | ||
167 | L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)> | |
168 | ||
8061d964 MC |
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 | ||
df75c2bf DMSP |
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. | |
cf72c757 | 178 | |
e2f92610 RS |
179 | =head1 COPYRIGHT |
180 | ||
18bad535 | 181 | Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
182 | |
183 | Licensed under the OpenSSL license (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 |