doc/ssl/SSL_CTX_set_split_send_fragment.pod - third_party/openssl - Git at Google

 =pod

 =head1 NAME

 SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment,
 SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment,
 SSL_CTX_set_max_pipelines, SSL_set_max_pipelines,
 SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len - Control
 fragment sizes and pipelining operations

 =head1 SYNOPSIS

  #include <openssl/ssl.h>

  # define SSL_CTX_set_max_send_fragment(ctx,m) \
          SSL_CTX_ctrl(ctx,SSL_CTRL_SET_MAX_SEND_FRAGMENT,m,NULL)
  # define SSL_set_max_send_fragment(ssl,m) \
          SSL_ctrl(ssl,SSL_CTRL_SET_MAX_SEND_FRAGMENT,m,NULL)
  # define SSL_CTX_set_max_pipelines(ctx,m) \
          SSL_CTX_ctrl(ctx,SSL_CTRL_SET_MAX_PIPELINES,m,NULL)
  # define SSL_set_max_pipelines(ssl,m) \
          SSL_ctrl(ssl,SSL_CTRL_SET_MAX_PIPELINES,m,NULL)
  # define SSL_CTX_set_split_send_fragment(ctx,m) \
          SSL_CTX_ctrl(ctx,SSL_CTRL_SET_SPLIT_SEND_FRAGMENT,m,NULL)
  # define SSL_set_split_send_fragment(ssl,m) \
          SSL_ctrl(ssl,SSL_CTRL_SET_SPLIT_SEND_FRAGMENT,m,NULL)

  void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
  void SSL_set_default_read_buffer_len(SSL *s, size_t len);

 =head1 DESCRIPTION

 Some engines are able to process multiple simultaneous crypto operations. This
 capability could be utilised to parallelise the processing of a single
 connection. For example a single write can be split into multiple records and
 each one encrypted independently and in parallel. Note: this will only work in
 TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This
 capability is known as "pipelining" within OpenSSL.

 In order to benefit from the pipelining capability. You need to have an engine
 that provides ciphers that support this. The OpenSSL "dasync" engine provides
 AES128-SHA based ciphers that have this capability. However these are for
 development and test purposes only.

 SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the
 B<max_send_fragment> parameter for SSL_CTX and SSL objects respectively. This
 value restricts the amount of plaintext bytes that will be sent in any one
 SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These
 functions will only accept a value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH.

 SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum number
 of pipelines that will be used at any one time. This value applies to both
 "read" pipelining and "write" pipelining. By default only one pipeline will be
 used (i.e. normal non-parallel operation). The number of pipelines set must be
 in the range 1 - SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also
 automatically turn on "read_ahead" (see L<SSL_CTX_set_read_ahead(3)>). This is
 explained further below. OpenSSL will only every use more than one pipeline if
 a ciphersuite is negotiated that uses a pipeline capable cipher provided by an
 engine.

 Pipelining operates slightly differently for reading encrypted data compared to
 writing encrypted data. SSL_CTX_set_split_send_fragment() and
 SSL_set_split_send_fragment() define how data is split up into pipelines when
 writing encrypted data. The number of pipelines used will be determined by the
 amount of data provided to the SSL_write() call divided by
 B<split_send_fragment>.

 For example if B<split_send_fragment> is set to 2000 and B<max_pipelines> is 4
 then:

 SSL_write called with 0-2000 bytes == 1 pipeline used

 SSL_write called with 2001-4000 bytes == 2 pipelines used

 SSL_write called with 4001-6000 bytes == 3 pipelines used

 SSL_write called with 6001+ bytes == 4 pipelines used

 B<split_send_fragment> must always be less than or equal to
 B<max_send_fragment>. By default it is set to be equal to B<max_send_fragment>.
 This will mean that the same number of records will always be created as would
 have been created in the non-parallel case, although the data will be
 apportioned differently. In the parallel case data will be spread equally
 between the pipelines.

 Read pipelining is controlled in a slightly different way than with write
 pipelining. While reading we are constrained by the number of records that the
 peer (and the network) can provide to us in one go. The more records we can get
 in one go the more opportunity we have to parallelise the processing. As noted
 above when setting B<max_pipelines> to a value greater than one, B<read_ahead>
 is automatically set. The B<read_ahead> parameter causes OpenSSL to attempt to
 read as much data into the read buffer as the network can provide and will fit
 into the buffer. Without this set data is read into the read buffer one record
 at a time. The more data that can be read, the more opportunity there is for
 parallelising the processing at the cost of increased memory overhead per
 connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending()
 function (see L<SSL_pending(3)>).

 The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
 functions control the size of the read buffer that will be used. The B<len>
 parameter sets the size of the buffer. The value will only be used if it is
 greater than the default that would have been used anyway. The normal default
 value depends on a number of factors but it will be at least
 SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes.

 =head1 RETURN VALUES

 All non-void functions return 1 on success and 0 on failure.

 =head1 NOTES

 With the exception of SSL_CTX_set_default_read_buffer_len() and
 SSL_set_default_read_buffer_len() all these functions are implemented using
 macros.

 =head1 HISTORY

 The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(),
 SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(),
 SSL_CTX_set_default_read_buffer_len() and  SSL_set_default_read_buffer_len()
 functions were added in OpenSSL 1.1.0.

 =head1 SEE ALSO

 L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>

 =head1 COPYRIGHT

 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.

 =cut
	=pod

	=head1 NAME

	SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment,
	SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment,
	SSL_CTX_set_max_pipelines, SSL_set_max_pipelines,
	SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len - Control
	fragment sizes and pipelining operations

	=head1 SYNOPSIS

	#include <openssl/ssl.h>

	# define SSL_CTX_set_max_send_fragment(ctx,m) \
	SSL_CTX_ctrl(ctx,SSL_CTRL_SET_MAX_SEND_FRAGMENT,m,NULL)
	# define SSL_set_max_send_fragment(ssl,m) \
	SSL_ctrl(ssl,SSL_CTRL_SET_MAX_SEND_FRAGMENT,m,NULL)
	# define SSL_CTX_set_max_pipelines(ctx,m) \
	SSL_CTX_ctrl(ctx,SSL_CTRL_SET_MAX_PIPELINES,m,NULL)
	# define SSL_set_max_pipelines(ssl,m) \
	SSL_ctrl(ssl,SSL_CTRL_SET_MAX_PIPELINES,m,NULL)
	# define SSL_CTX_set_split_send_fragment(ctx,m) \
	SSL_CTX_ctrl(ctx,SSL_CTRL_SET_SPLIT_SEND_FRAGMENT,m,NULL)
	# define SSL_set_split_send_fragment(ssl,m) \
	SSL_ctrl(ssl,SSL_CTRL_SET_SPLIT_SEND_FRAGMENT,m,NULL)

	void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
	void SSL_set_default_read_buffer_len(SSL *s, size_t len);

	=head1 DESCRIPTION

	Some engines are able to process multiple simultaneous crypto operations. This
	capability could be utilised to parallelise the processing of a single
	connection. For example a single write can be split into multiple records and
	each one encrypted independently and in parallel. Note: this will only work in
	TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This
	capability is known as "pipelining" within OpenSSL.

	In order to benefit from the pipelining capability. You need to have an engine
	that provides ciphers that support this. The OpenSSL "dasync" engine provides
	AES128-SHA based ciphers that have this capability. However these are for
	development and test purposes only.

	SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the
	B<max_send_fragment> parameter for SSL_CTX and SSL objects respectively. This
	value restricts the amount of plaintext bytes that will be sent in any one
	SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These
	functions will only accept a value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH.

	SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum number
	of pipelines that will be used at any one time. This value applies to both
	"read" pipelining and "write" pipelining. By default only one pipeline will be
	used (i.e. normal non-parallel operation). The number of pipelines set must be
	in the range 1 - SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also
	automatically turn on "read_ahead" (see L<SSL_CTX_set_read_ahead(3)>). This is
	explained further below. OpenSSL will only every use more than one pipeline if
	a ciphersuite is negotiated that uses a pipeline capable cipher provided by an
	engine.

	Pipelining operates slightly differently for reading encrypted data compared to
	writing encrypted data. SSL_CTX_set_split_send_fragment() and
	SSL_set_split_send_fragment() define how data is split up into pipelines when
	writing encrypted data. The number of pipelines used will be determined by the
	amount of data provided to the SSL_write() call divided by
	B<split_send_fragment>.

	For example if B<split_send_fragment> is set to 2000 and B<max_pipelines> is 4
	then:

	SSL_write called with 0-2000 bytes == 1 pipeline used

	SSL_write called with 2001-4000 bytes == 2 pipelines used

	SSL_write called with 4001-6000 bytes == 3 pipelines used

	SSL_write called with 6001+ bytes == 4 pipelines used

	B<split_send_fragment> must always be less than or equal to
	B<max_send_fragment>. By default it is set to be equal to B<max_send_fragment>.
	This will mean that the same number of records will always be created as would
	have been created in the non-parallel case, although the data will be
	apportioned differently. In the parallel case data will be spread equally
	between the pipelines.

	Read pipelining is controlled in a slightly different way than with write
	pipelining. While reading we are constrained by the number of records that the
	peer (and the network) can provide to us in one go. The more records we can get
	in one go the more opportunity we have to parallelise the processing. As noted
	above when setting B<max_pipelines> to a value greater than one, B<read_ahead>
	is automatically set. The B<read_ahead> parameter causes OpenSSL to attempt to
	read as much data into the read buffer as the network can provide and will fit
	into the buffer. Without this set data is read into the read buffer one record
	at a time. The more data that can be read, the more opportunity there is for
	parallelising the processing at the cost of increased memory overhead per
	connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending()
	function (see L<SSL_pending(3)>).

	The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
	functions control the size of the read buffer that will be used. The B<len>
	parameter sets the size of the buffer. The value will only be used if it is
	greater than the default that would have been used anyway. The normal default
	value depends on a number of factors but it will be at least
	SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes.

	=head1 RETURN VALUES

	All non-void functions return 1 on success and 0 on failure.

	=head1 NOTES

	With the exception of SSL_CTX_set_default_read_buffer_len() and
	SSL_set_default_read_buffer_len() all these functions are implemented using
	macros.

	=head1 HISTORY

	The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(),
	SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(),
	SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
	functions were added in OpenSSL 1.1.0.

	=head1 SEE ALSO

	L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>

	=head1 COPYRIGHT

	Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

	Licensed under the OpenSSL license (the "License"). You may not use
	this file except in compliance with the License. You can obtain a copy
	in the file LICENSE in the source distribution or at
	L<https://www.openssl.org/source/license.html>.

	=cut