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(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 every 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)>). 100 101The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len() 102functions control the size of the read buffer that will be used. The B<len> 103parameter sets the size of the buffer. The value will only be used if it is 104greater than the default that would have been used anyway. The normal default 105value depends on a number of factors but it will be at least 106SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes. 107 108SSL_CTX_set_tlsext_max_fragment_length() sets the default maximum fragment 109length negotiation mode via value B<mode> to B<ctx>. 110This setting affects only SSL instances created after this function is called. 111It affects the client-side as only its side may initiate this extension use. 112 113SSL_set_tlsext_max_fragment_length() sets the maximum fragment length 114negotiation mode via value B<mode> to B<ssl>. 115This setting will be used during a handshake when extensions are exchanged 116between client and server. 117So it only affects SSL sessions created after this function is called. 118It affects the client-side as only its side may initiate this extension use. 119 120SSL_SESSION_get_max_fragment_length() gets the maximum fragment length 121negotiated in B<session>. 122 123=head1 RETURN VALUES 124 125All non-void functions return 1 on success and 0 on failure. 126 127=head1 NOTES 128 129The Maximum Fragment Length extension support is optional on the server side. 130If the server does not support this extension then 131SSL_SESSION_get_max_fragment_length() will return: 132TLSEXT_max_fragment_length_DISABLED. 133 134The following modes are available: 135 136=over 4 137 138=item TLSEXT_max_fragment_length_DISABLED 139 140Disables Maximum Fragment Length Negotiation (default). 141 142=item TLSEXT_max_fragment_length_512 143 144Sets Maximum Fragment Length to 512 bytes. 145 146=item TLSEXT_max_fragment_length_1024 147 148Sets Maximum Fragment Length to 1024. 149 150=item TLSEXT_max_fragment_length_2048 151 152Sets Maximum Fragment Length to 2048. 153 154=item TLSEXT_max_fragment_length_4096 155 156Sets Maximum Fragment Length to 4096. 157 158=back 159 160With the exception of SSL_CTX_set_default_read_buffer_len() 161SSL_set_default_read_buffer_len(), SSL_CTX_set_tlsext_max_fragment_length(), 162SSL_set_tlsext_max_fragment_length() and SSL_SESSION_get_max_fragment_length() 163all these functions are implemented using macros. 164 165=head1 SEE ALSO 166 167L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)> 168 169=head1 HISTORY 170 171The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(), 172SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(), 173SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len() 174functions were added in OpenSSL 1.1.0. 175 176The SSL_CTX_set_tlsext_max_fragment_length(), SSL_set_tlsext_max_fragment_length() 177and SSL_SESSION_get_max_fragment_length() functions were added in OpenSSL 1.1.1. 178 179=head1 COPYRIGHT 180 181Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. 182 183Licensed under the OpenSSL license (the "License"). You may not use 184this file except in compliance with the License. You can obtain a copy 185in the file LICENSE in the source distribution or at 186L<https://www.openssl.org/source/license.html>. 187 188=cut 189