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