|
Packit |
c4476c |
=pod
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NAME
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment,
|
|
Packit |
c4476c |
SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment,
|
|
Packit |
c4476c |
SSL_CTX_set_max_pipelines, SSL_set_max_pipelines,
|
|
Packit |
c4476c |
SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len,
|
|
Packit |
c4476c |
SSL_CTX_set_tlsext_max_fragment_length,
|
|
Packit |
c4476c |
SSL_set_tlsext_max_fragment_length,
|
|
Packit |
c4476c |
SSL_SESSION_get_max_fragment_length - Control fragment size settings and pipelining operations
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SYNOPSIS
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
#include <openssl/ssl.h>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long);
|
|
Packit |
c4476c |
long SSL_set_max_send_fragment(SSL *ssl, long m);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m);
|
|
Packit |
c4476c |
long SSL_set_max_pipelines(SSL_CTX *ssl, long m);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m);
|
|
Packit |
c4476c |
long SSL_set_split_send_fragment(SSL *ssl, long m);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
|
|
Packit |
c4476c |
void SSL_set_default_read_buffer_len(SSL *s, size_t len);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
int SSL_CTX_set_tlsext_max_fragment_length(SSL_CTX *ctx, uint8_t mode);
|
|
Packit |
c4476c |
int SSL_set_tlsext_max_fragment_length(SSL *ssl, uint8_t mode);
|
|
Packit |
c4476c |
uint8_t SSL_SESSION_get_max_fragment_length(SSL_SESSION *session);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 DESCRIPTION
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Some engines are able to process multiple simultaneous crypto operations. This
|
|
Packit |
c4476c |
capability could be utilised to parallelise the processing of a single
|
|
Packit |
c4476c |
connection. For example a single write can be split into multiple records and
|
|
Packit |
c4476c |
each one encrypted independently and in parallel. Note: this will only work in
|
|
Packit |
c4476c |
TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This
|
|
Packit |
c4476c |
capability is known as "pipelining" within OpenSSL.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
In order to benefit from the pipelining capability. You need to have an engine
|
|
Packit |
c4476c |
that provides ciphers that support this. The OpenSSL "dasync" engine provides
|
|
Packit |
c4476c |
AES128-SHA based ciphers that have this capability. However these are for
|
|
Packit |
c4476c |
development and test purposes only.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the
|
|
Packit |
c4476c |
B<max_send_fragment> parameter for SSL_CTX and SSL objects respectively. This
|
|
Packit |
c4476c |
value restricts the amount of plaintext bytes that will be sent in any one
|
|
Packit |
c4476c |
SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These
|
|
Packit |
c4476c |
functions will only accept a value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum number
|
|
Packit |
c4476c |
of pipelines that will be used at any one time. This value applies to both
|
|
Packit |
c4476c |
"read" pipelining and "write" pipelining. By default only one pipeline will be
|
|
Packit |
c4476c |
used (i.e. normal non-parallel operation). The number of pipelines set must be
|
|
Packit |
c4476c |
in the range 1 - SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also
|
|
Packit |
c4476c |
automatically turn on "read_ahead" (see L<SSL_CTX_set_read_ahead(3)>). This is
|
|
Packit |
c4476c |
explained further below. OpenSSL will only every use more than one pipeline if
|
|
Packit |
c4476c |
a cipher suite is negotiated that uses a pipeline capable cipher provided by an
|
|
Packit |
c4476c |
engine.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Pipelining operates slightly differently for reading encrypted data compared to
|
|
Packit |
c4476c |
writing encrypted data. SSL_CTX_set_split_send_fragment() and
|
|
Packit |
c4476c |
SSL_set_split_send_fragment() define how data is split up into pipelines when
|
|
Packit |
c4476c |
writing encrypted data. The number of pipelines used will be determined by the
|
|
Packit |
c4476c |
amount of data provided to the SSL_write_ex() or SSL_write() call divided by
|
|
Packit |
c4476c |
B<split_send_fragment>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
For example if B<split_send_fragment> is set to 2000 and B<max_pipelines> is 4
|
|
Packit |
c4476c |
then:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_write/SSL_write_ex called with 0-2000 bytes == 1 pipeline used
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_write/SSL_write_ex called with 2001-4000 bytes == 2 pipelines used
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_write/SSL_write_ex called with 4001-6000 bytes == 3 pipelines used
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_write/SSL_write_ex called with 6001+ bytes == 4 pipelines used
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
B<split_send_fragment> must always be less than or equal to
|
|
Packit |
c4476c |
B<max_send_fragment>. By default it is set to be equal to B<max_send_fragment>.
|
|
Packit |
c4476c |
This will mean that the same number of records will always be created as would
|
|
Packit |
c4476c |
have been created in the non-parallel case, although the data will be
|
|
Packit |
c4476c |
apportioned differently. In the parallel case data will be spread equally
|
|
Packit |
c4476c |
between the pipelines.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Read pipelining is controlled in a slightly different way than with write
|
|
Packit |
c4476c |
pipelining. While reading we are constrained by the number of records that the
|
|
Packit |
c4476c |
peer (and the network) can provide to us in one go. The more records we can get
|
|
Packit |
c4476c |
in one go the more opportunity we have to parallelise the processing. As noted
|
|
Packit |
c4476c |
above when setting B<max_pipelines> to a value greater than one, B<read_ahead>
|
|
Packit |
c4476c |
is automatically set. The B<read_ahead> parameter causes OpenSSL to attempt to
|
|
Packit |
c4476c |
read as much data into the read buffer as the network can provide and will fit
|
|
Packit |
c4476c |
into the buffer. Without this set data is read into the read buffer one record
|
|
Packit |
c4476c |
at a time. The more data that can be read, the more opportunity there is for
|
|
Packit |
c4476c |
parallelising the processing at the cost of increased memory overhead per
|
|
Packit |
c4476c |
connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending()
|
|
Packit |
c4476c |
function (see L<SSL_pending(3)>).
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
|
|
Packit |
c4476c |
functions control the size of the read buffer that will be used. The B<len>
|
|
Packit |
c4476c |
parameter sets the size of the buffer. The value will only be used if it is
|
|
Packit |
c4476c |
greater than the default that would have been used anyway. The normal default
|
|
Packit |
c4476c |
value depends on a number of factors but it will be at least
|
|
Packit |
c4476c |
SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_set_tlsext_max_fragment_length() sets the default maximum fragment
|
|
Packit |
c4476c |
length negotiation mode via value B<mode> to B<ctx>.
|
|
Packit |
c4476c |
This setting affects only SSL instances created after this function is called.
|
|
Packit |
c4476c |
It affects the client-side as only its side may initiate this extension use.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_set_tlsext_max_fragment_length() sets the maximum fragment length
|
|
Packit |
c4476c |
negotiation mode via value B<mode> to B<ssl>.
|
|
Packit |
c4476c |
This setting will be used during a handshake when extensions are exchanged
|
|
Packit |
c4476c |
between client and server.
|
|
Packit |
c4476c |
So it only affects SSL sessions created after this function is called.
|
|
Packit |
c4476c |
It affects the client-side as only its side may initiate this extension use.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_SESSION_get_max_fragment_length() gets the maximum fragment length
|
|
Packit |
c4476c |
negotiated in B<session>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 RETURN VALUES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
All non-void functions return 1 on success and 0 on failure.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NOTES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The Maximum Fragment Length extension support is optional on the server side.
|
|
Packit |
c4476c |
If the server does not support this extension then
|
|
Packit |
c4476c |
SSL_SESSION_get_max_fragment_length() will return:
|
|
Packit |
c4476c |
TLSEXT_max_fragment_length_DISABLED.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The following modes are available:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=over 4
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item TLSEXT_max_fragment_length_DISABLED
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Disables Maximum Fragment Length Negotiation (default).
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item TLSEXT_max_fragment_length_512
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Sets Maximum Fragment Length to 512 bytes.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item TLSEXT_max_fragment_length_1024
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Sets Maximum Fragment Length to 1024.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item TLSEXT_max_fragment_length_2048
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Sets Maximum Fragment Length to 2048.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item TLSEXT_max_fragment_length_4096
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Sets Maximum Fragment Length to 4096.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=back
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
With the exception of SSL_CTX_set_default_read_buffer_len()
|
|
Packit |
c4476c |
SSL_set_default_read_buffer_len(), SSL_CTX_set_tlsext_max_fragment_length(),
|
|
Packit |
c4476c |
SSL_set_tlsext_max_fragment_length() and SSL_SESSION_get_max_fragment_length()
|
|
Packit |
c4476c |
all these functions are implemented using macros.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SEE ALSO
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 HISTORY
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(),
|
|
Packit |
c4476c |
SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(),
|
|
Packit |
c4476c |
SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
|
|
Packit |
c4476c |
functions were added in OpenSSL 1.1.0.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The SSL_CTX_set_tlsext_max_fragment_length(), SSL_set_tlsext_max_fragment_length()
|
|
Packit |
c4476c |
and SSL_SESSION_get_max_fragment_length() functions were added in OpenSSL 1.1.1.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 COPYRIGHT
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Licensed under the OpenSSL license (the "License"). You may not use
|
|
Packit |
c4476c |
this file except in compliance with the License. You can obtain a copy
|
|
Packit |
c4476c |
in the file LICENSE in the source distribution or at
|
|
Packit |
c4476c |
L<https://www.openssl.org/source/license.html>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=cut
|