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 - Control
   9 fragment sizes and pipelining operations
  10
  11 =head1 SYNOPSIS
  12
  13  #include <openssl/ssl.h>
  14
  15  long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long);
  16  long SSL_set_max_send_fragment(SSL *ssl, long m);
  17
  18  long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m);
  19  long SSL_set_max_pipelines(SSL_CTX *ssl, long m);
  20
  21  long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m);
  22  long SSL_set_split_send_fragment(SSL *ssl, long m);
  23
  24  void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
  25  void SSL_set_default_read_buffer_len(SSL *s, size_t len);
  26
  27 =head1 DESCRIPTION
  28
  29 Some engines are able to process multiple simultaneous crypto operations. This
  30 capability could be utilised to parallelise the processing of a single
  31 connection. For example a single write can be split into multiple records and
  32 each one encrypted independently and in parallel. Note: this will only work in
  33 TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This
  34 capability is known as "pipelining" within OpenSSL.
  35
  36 In order to benefit from the pipelining capability. You need to have an engine
  37 that provides ciphers that support this. The OpenSSL "dasync" engine provides
  38 AES128-SHA based ciphers that have this capability. However these are for
  39 development and test purposes only.
  40
  41 SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the
  42 B<max_send_fragment> parameter for SSL_CTX and SSL objects respectively. This
  43 value restricts the amount of plaintext bytes that will be sent in any one
  44 SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These
  45 functions will only accept a value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH.
  46
  47 SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum number
  48 of pipelines that will be used at any one time. This value applies to both
  49 "read" pipelining and "write" pipelining. By default only one pipeline will be
  50 used (i.e. normal non-parallel operation). The number of pipelines set must be
  51 in the range 1 - SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also
  52 automatically turn on "read_ahead" (see L<SSL_CTX_set_read_ahead(3)>). This is
  53 explained further below. OpenSSL will only every use more than one pipeline if
  54 a ciphersuite is negotiated that uses a pipeline capable cipher provided by an
  55 engine.
  56
  57 Pipelining operates slightly differently for reading encrypted data compared to
  58 writing encrypted data. SSL_CTX_set_split_send_fragment() and
  59 SSL_set_split_send_fragment() define how data is split up into pipelines when
  60 writing encrypted data. The number of pipelines used will be determined by the
  61 amount of data provided to the SSL_write() call divided by
  62 B<split_send_fragment>.
  63
  64 For example if B<split_send_fragment> is set to 2000 and B<max_pipelines> is 4
  65 then:
  66
  67 SSL_write called with 0-2000 bytes == 1 pipeline used
  68
  69 SSL_write called with 2001-4000 bytes == 2 pipelines used
  70
  71 SSL_write called with 4001-6000 bytes == 3 pipelines used
  72
  73 SSL_write called with 6001+ bytes == 4 pipelines used
  74
  75 B<split_send_fragment> must always be less than or equal to
  76 B<max_send_fragment>. By default it is set to be equal to B<max_send_fragment>.
  77 This will mean that the same number of records will always be created as would
  78 have been created in the non-parallel case, although the data will be
  79 apportioned differently. In the parallel case data will be spread equally
  80 between the pipelines.
  81
  82 Read pipelining is controlled in a slightly different way than with write
  83 pipelining. While reading we are constrained by the number of records that the
  84 peer (and the network) can provide to us in one go. The more records we can get
  85 in one go the more opportunity we have to parallelise the processing. As noted
  86 above when setting B<max_pipelines> to a value greater than one, B<read_ahead>
  87 is automatically set. The B<read_ahead> parameter causes OpenSSL to attempt to
  88 read as much data into the read buffer as the network can provide and will fit
  89 into the buffer. Without this set data is read into the read buffer one record
  90 at a time. The more data that can be read, the more opportunity there is for
  91 parallelising the processing at the cost of increased memory overhead per
  92 connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending()
  93 function (see L<SSL_pending(3)>).
  94
  95 The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
  96 functions control the size of the read buffer that will be used. The B<len>
  97 parameter sets the size of the buffer. The value will only be used if it is
  98 greater than the default that would have been used anyway. The normal default
  99 value depends on a number of factors but it will be at least
 100 SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes.
 101
 102 =head1 RETURN VALUES
 103
 104 All non-void functions return 1 on success and 0 on failure.
 105
 106 =head1 NOTES
 107
 108 With the exception of SSL_CTX_set_default_read_buffer_len() and
 109 SSL_set_default_read_buffer_len() all these functions are implemented using
 110 macros.
 111
 112 =head1 HISTORY
 113
 114 The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(),
 115 SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(),
 116 SSL_CTX_set_default_read_buffer_len() and  SSL_set_default_read_buffer_len()
 117 functions were added in OpenSSL 1.1.0.
 118
 119 =head1 SEE ALSO
 120
 121 L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>
 122
 123 =head1 COPYRIGHT
 124
 125 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
 126
 127 Licensed under the OpenSSL license (the "License").  You may not use
 128 this file except in compliance with the License.  You can obtain a copy
 129 in the file LICENSE in the source distribution or at
 130 L<https://www.openssl.org/source/license.html>.
 131
 132 =cut