From 8061d964e794b9f3beafec155ffe2e1d3c9eaf60 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Mon, 15 Feb 2016 15:45:18 +0000 Subject: [PATCH] Add pipelining documentation Add some documentation for all of the SSL/SSL_CTX functions/ctrls for conrolling read and write pipelining. Reviewed-by: Tim Hudson --- doc/ssl/SSL_CTX_set_split_send_fragment.pod | 126 ++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 doc/ssl/SSL_CTX_set_split_send_fragment.pod diff --git a/doc/ssl/SSL_CTX_set_split_send_fragment.pod b/doc/ssl/SSL_CTX_set_split_send_fragment.pod new file mode 100644 index 0000000000..b729b8165f --- /dev/null +++ b/doc/ssl/SSL_CTX_set_split_send_fragment.pod @@ -0,0 +1,126 @@ +=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 + + # 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 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). 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 slighly 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. + +For example if B is set to 2000 and B 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 must always be less than or equal to +B. By default it is set to be equal to B. +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 to a value greater than one, B +is automatically set. The B 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. + +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 +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 + +=cut -- GitLab