secure/lib/libcrypto/man/man3/SSL_CTX_set_split_send_fragment.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_CTX_SET_SPLIT_SEND_FRAGMENT 3"
 136 .TH SSL_CTX_SET_SPLIT_SEND_FRAGMENT 3 "2020-04-21" "1.1.1g" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 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, SSL_CTX_set_tlsext_max_fragment_length, SSL_set_tlsext_max_fragment_length, SSL_SESSION_get_max_fragment_length \- Control fragment size settings and pipelining operations
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long);
 149 \& long SSL_set_max_send_fragment(SSL *ssl, long m);
 150 \&
 151 \& long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m);
 152 \& long SSL_set_max_pipelines(SSL_CTX *ssl, long m);
 153 \&
 154 \& long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m);
 155 \& long SSL_set_split_send_fragment(SSL *ssl, long m);
 156 \&
 157 \& void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
 158 \& void SSL_set_default_read_buffer_len(SSL *s, size_t len);
 159 \&
 160 \& int SSL_CTX_set_tlsext_max_fragment_length(SSL_CTX *ctx, uint8_t mode);
 161 \& int SSL_set_tlsext_max_fragment_length(SSL *ssl, uint8_t mode);
 162 \& uint8_t SSL_SESSION_get_max_fragment_length(SSL_SESSION *session);
 163 .Ve
 164 .SH "DESCRIPTION"
 165 .IX Header "DESCRIPTION"
 166 Some engines are able to process multiple simultaneous crypto operations. This
 167 capability could be utilised to parallelise the processing of a single
 168 connection. For example a single write can be split into multiple records and
 169 each one encrypted independently and in parallel. Note: this will only work in
 170 \&\s-1TLS1.1+.\s0 There is no support in SSLv3, TLSv1.0 or \s-1DTLS\s0 (any version). This
 171 capability is known as \*(L"pipelining\*(R" within OpenSSL.
 172 .PP
 173 In order to benefit from the pipelining capability. You need to have an engine
 174 that provides ciphers that support this. The OpenSSL \*(L"dasync\*(R" engine provides
 175 \&\s-1AES128\-SHA\s0 based ciphers that have this capability. However these are for
 176 development and test purposes only.
 177 .PP
 178 \&\fBSSL_CTX_set_max_send_fragment()\fR and \fBSSL_set_max_send_fragment()\fR set the
 179 \&\fBmax_send_fragment\fR parameter for \s-1SSL_CTX\s0 and \s-1SSL\s0 objects respectively. This
 180 value restricts the amount of plaintext bytes that will be sent in any one
 181 \&\s-1SSL/TLS\s0 record. By default its value is \s-1SSL3_RT_MAX_PLAIN_LENGTH\s0 (16384). These
 182 functions will only accept a value in the range 512 \- \s-1SSL3_RT_MAX_PLAIN_LENGTH.\s0
 183 .PP
 184 \&\fBSSL_CTX_set_max_pipelines()\fR and \fBSSL_set_max_pipelines()\fR set the maximum number
 185 of pipelines that will be used at any one time. This value applies to both
 186 \&\*(L"read\*(R" pipelining and \*(L"write\*(R" pipelining. By default only one pipeline will be
 187 used (i.e. normal non-parallel operation). The number of pipelines set must be
 188 in the range 1 \- \s-1SSL_MAX_PIPELINES\s0 (32). Setting this to a value > 1 will also
 189 automatically turn on \*(L"read_ahead\*(R" (see \fBSSL_CTX_set_read_ahead\fR\|(3)). This is
 190 explained further below. OpenSSL will only every use more than one pipeline if
 191 a cipher suite is negotiated that uses a pipeline capable cipher provided by an
 192 engine.
 193 .PP
 194 Pipelining operates slightly differently for reading encrypted data compared to
 195 writing encrypted data. \fBSSL_CTX_set_split_send_fragment()\fR and
 196 \&\fBSSL_set_split_send_fragment()\fR define how data is split up into pipelines when
 197 writing encrypted data. The number of pipelines used will be determined by the
 198 amount of data provided to the \fBSSL_write_ex()\fR or \fBSSL_write()\fR call divided by
 199 \&\fBsplit_send_fragment\fR.
 200 .PP
 201 For example if \fBsplit_send_fragment\fR is set to 2000 and \fBmax_pipelines\fR is 4
 202 then:
 203 .PP
 204 SSL_write/SSL_write_ex called with 0\-2000 bytes == 1 pipeline used
 205 .PP
 206 SSL_write/SSL_write_ex called with 2001\-4000 bytes == 2 pipelines used
 207 .PP
 208 SSL_write/SSL_write_ex called with 4001\-6000 bytes == 3 pipelines used
 209 .PP
 210 SSL_write/SSL_write_ex called with 6001+ bytes == 4 pipelines used
 211 .PP
 212 \&\fBsplit_send_fragment\fR must always be less than or equal to
 213 \&\fBmax_send_fragment\fR. By default it is set to be equal to \fBmax_send_fragment\fR.
 214 This will mean that the same number of records will always be created as would
 215 have been created in the non-parallel case, although the data will be
 216 apportioned differently. In the parallel case data will be spread equally
 217 between the pipelines.
 218 .PP
 219 Read pipelining is controlled in a slightly different way than with write
 220 pipelining. While reading we are constrained by the number of records that the
 221 peer (and the network) can provide to us in one go. The more records we can get
 222 in one go the more opportunity we have to parallelise the processing. As noted
 223 above when setting \fBmax_pipelines\fR to a value greater than one, \fBread_ahead\fR
 224 is automatically set. The \fBread_ahead\fR parameter causes OpenSSL to attempt to
 225 read as much data into the read buffer as the network can provide and will fit
 226 into the buffer. Without this set data is read into the read buffer one record
 227 at a time. The more data that can be read, the more opportunity there is for
 228 parallelising the processing at the cost of increased memory overhead per
 229 connection. Setting \fBread_ahead\fR can impact the behaviour of the \fBSSL_pending()\fR
 230 function (see \fBSSL_pending\fR\|(3)).
 231 .PP
 232 The \fBSSL_CTX_set_default_read_buffer_len()\fR and \fBSSL_set_default_read_buffer_len()\fR
 233 functions control the size of the read buffer that will be used. The \fBlen\fR
 234 parameter sets the size of the buffer. The value will only be used if it is
 235 greater than the default that would have been used anyway. The normal default
 236 value depends on a number of factors but it will be at least
 237 \&\s-1SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD\s0 (16704) bytes.
 238 .PP
 239 \&\fBSSL_CTX_set_tlsext_max_fragment_length()\fR sets the default maximum fragment
 240 length negotiation mode via value \fBmode\fR to \fBctx\fR.
 241 This setting affects only \s-1SSL\s0 instances created after this function is called.
 242 It affects the client-side as only its side may initiate this extension use.
 243 .PP
 244 \&\fBSSL_set_tlsext_max_fragment_length()\fR sets the maximum fragment length
 245 negotiation mode via value \fBmode\fR to \fBssl\fR.
 246 This setting will be used during a handshake when extensions are exchanged
 247 between client and server.
 248 So it only affects \s-1SSL\s0 sessions created after this function is called.
 249 It affects the client-side as only its side may initiate this extension use.
 250 .PP
 251 \&\fBSSL_SESSION_get_max_fragment_length()\fR gets the maximum fragment length
 252 negotiated in \fBsession\fR.
 253 .SH "RETURN VALUES"
 254 .IX Header "RETURN VALUES"
 255 All non-void functions return 1 on success and 0 on failure.
 256 .SH "NOTES"
 257 .IX Header "NOTES"
 258 The Maximum Fragment Length extension support is optional on the server side.
 259 If the server does not support this extension then
 260 \&\fBSSL_SESSION_get_max_fragment_length()\fR will return:
 261 TLSEXT_max_fragment_length_DISABLED.
 262 .PP
 263 The following modes are available:
 264 .IP "TLSEXT_max_fragment_length_DISABLED" 4
 265 .IX Item "TLSEXT_max_fragment_length_DISABLED"
 266 Disables Maximum Fragment Length Negotiation (default).
 267 .IP "TLSEXT_max_fragment_length_512" 4
 268 .IX Item "TLSEXT_max_fragment_length_512"
 269 Sets Maximum Fragment Length to 512 bytes.
 270 .IP "TLSEXT_max_fragment_length_1024" 4
 271 .IX Item "TLSEXT_max_fragment_length_1024"
 272 Sets Maximum Fragment Length to 1024.
 273 .IP "TLSEXT_max_fragment_length_2048" 4
 274 .IX Item "TLSEXT_max_fragment_length_2048"
 275 Sets Maximum Fragment Length to 2048.
 276 .IP "TLSEXT_max_fragment_length_4096" 4
 277 .IX Item "TLSEXT_max_fragment_length_4096"
 278 Sets Maximum Fragment Length to 4096.
 279 .PP
 280 With the exception of \fBSSL_CTX_set_default_read_buffer_len()\fR
 281 \&\fBSSL_set_default_read_buffer_len()\fR, \fBSSL_CTX_set_tlsext_max_fragment_length()\fR,
 282 \&\fBSSL_set_tlsext_max_fragment_length()\fR and \fBSSL_SESSION_get_max_fragment_length()\fR
 283 all these functions are implemented using macros.
 284 .SH "SEE ALSO"
 285 .IX Header "SEE ALSO"
 286 \&\fBSSL_CTX_set_read_ahead\fR\|(3), \fBSSL_pending\fR\|(3)
 287 .SH "HISTORY"
 288 .IX Header "HISTORY"
 289 The \fBSSL_CTX_set_max_pipelines()\fR, \fBSSL_set_max_pipelines()\fR,
 290 \&\fBSSL_CTX_set_split_send_fragment()\fR, \fBSSL_set_split_send_fragment()\fR,
 291 \&\fBSSL_CTX_set_default_read_buffer_len()\fR and  \fBSSL_set_default_read_buffer_len()\fR
 292 functions were added in OpenSSL 1.1.0.
 293 .PP
 294 The \fBSSL_CTX_set_tlsext_max_fragment_length()\fR, \fBSSL_set_tlsext_max_fragment_length()\fR
 295 and \fBSSL_SESSION_get_max_fragment_length()\fR functions were added in OpenSSL 1.1.1.
 296 .SH "COPYRIGHT"
 297 .IX Header "COPYRIGHT"
 298 Copyright 2016\-2019 The OpenSSL Project Authors. All Rights Reserved.
 299 .PP
 300 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 301 this file except in compliance with the License.  You can obtain a copy
 302 in the file \s-1LICENSE\s0 in the source distribution or at
 303 <https://www.openssl.org/source/license.html>.