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