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

   1 .\" Automatically generated by Pod::Man 4.14 (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_OPTIONS 3"
 136 .TH SSL_CTX_SET_OPTIONS 3 "2020-09-22" "1.1.1h" "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_options, SSL_set_options, SSL_CTX_clear_options, SSL_clear_options, SSL_CTX_get_options, SSL_get_options, SSL_get_secure_renegotiation_support \- manipulate SSL options
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& long SSL_CTX_set_options(SSL_CTX *ctx, long options);
 149 \& long SSL_set_options(SSL *ssl, long options);
 150 \&
 151 \& long SSL_CTX_clear_options(SSL_CTX *ctx, long options);
 152 \& long SSL_clear_options(SSL *ssl, long options);
 153 \&
 154 \& long SSL_CTX_get_options(SSL_CTX *ctx);
 155 \& long SSL_get_options(SSL *ssl);
 156 \&
 157 \& long SSL_get_secure_renegotiation_support(SSL *ssl);
 158 .Ve
 159 .SH "DESCRIPTION"
 160 .IX Header "DESCRIPTION"
 161 \&\fBSSL_CTX_set_options()\fR adds the options set via bit mask in \fBoptions\fR to \fBctx\fR.
 162 Options already set before are not cleared!
 163 .PP
 164 \&\fBSSL_set_options()\fR adds the options set via bit mask in \fBoptions\fR to \fBssl\fR.
 165 Options already set before are not cleared!
 166 .PP
 167 \&\fBSSL_CTX_clear_options()\fR clears the options set via bit mask in \fBoptions\fR
 168 to \fBctx\fR.
 169 .PP
 170 \&\fBSSL_clear_options()\fR clears the options set via bit mask in \fBoptions\fR to \fBssl\fR.
 171 .PP
 172 \&\fBSSL_CTX_get_options()\fR returns the options set for \fBctx\fR.
 173 .PP
 174 \&\fBSSL_get_options()\fR returns the options set for \fBssl\fR.
 175 .PP
 176 \&\fBSSL_get_secure_renegotiation_support()\fR indicates whether the peer supports
 177 secure renegotiation.
 178 Note, this is implemented via a macro.
 179 .SH "NOTES"
 180 .IX Header "NOTES"
 181 The behaviour of the \s-1SSL\s0 library can be changed by setting several options.
 182 The options are coded as bit masks and can be combined by a bitwise \fBor\fR
 183 operation (|).
 184 .PP
 185 \&\fBSSL_CTX_set_options()\fR and \fBSSL_set_options()\fR affect the (external)
 186 protocol behaviour of the \s-1SSL\s0 library. The (internal) behaviour of
 187 the \s-1API\s0 can be changed by using the similar
 188 \&\fBSSL_CTX_set_mode\fR\|(3) and \fBSSL_set_mode()\fR functions.
 189 .PP
 190 During a handshake, the option settings of the \s-1SSL\s0 object are used. When
 191 a new \s-1SSL\s0 object is created from a context using \fBSSL_new()\fR, the current
 192 option setting is copied. Changes to \fBctx\fR do not affect already created
 193 \&\s-1SSL\s0 objects. \fBSSL_clear()\fR does not affect the settings.
 194 .PP
 195 The following \fBbug workaround\fR options are available:
 196 .IP "\s-1SSL_OP_SAFARI_ECDHE_ECDSA_BUG\s0" 4
 197 .IX Item "SSL_OP_SAFARI_ECDHE_ECDSA_BUG"
 198 Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on \s-1OS X.
 199 OS X 10.8..10.8.3\s0 has broken support for ECDHE-ECDSA ciphers.
 200 .IP "\s-1SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS\s0" 4
 201 .IX Item "SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS"
 202 Disables a countermeasure against a \s-1SSL 3.0/TLS 1.0\s0 protocol
 203 vulnerability affecting \s-1CBC\s0 ciphers, which cannot be handled by some
 204 broken \s-1SSL\s0 implementations.  This option has no effect for connections
 205 using other ciphers.
 206 .IP "\s-1SSL_OP_TLSEXT_PADDING\s0" 4
 207 .IX Item "SSL_OP_TLSEXT_PADDING"
 208 Adds a padding extension to ensure the ClientHello size is never between
 209 256 and 511 bytes in length. This is needed as a workaround for some
 210 implementations.
 211 .IP "\s-1SSL_OP_ALL\s0" 4
 212 .IX Item "SSL_OP_ALL"
 213 All of the above bug workarounds plus \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR as
 214 mentioned below.
 215 .PP
 216 It is usually safe to use \fB\s-1SSL_OP_ALL\s0\fR to enable the bug workaround
 217 options if compatibility with somewhat broken implementations is
 218 desired.
 219 .PP
 220 The following \fBmodifying\fR options are available:
 221 .IP "\s-1SSL_OP_TLS_ROLLBACK_BUG\s0" 4
 222 .IX Item "SSL_OP_TLS_ROLLBACK_BUG"
 223 Disable version rollback attack detection.
 224 .Sp
 225 During the client key exchange, the client must send the same information
 226 about acceptable \s-1SSL/TLS\s0 protocol levels as during the first hello. Some
 227 clients violate this rule by adapting to the server's answer. (Example:
 228 the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
 229 only understands up to SSLv3. In this case the client must still use the
 230 same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
 231 to the server's answer and violate the version rollback protection.)
 232 .IP "\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0" 4
 233 .IX Item "SSL_OP_CIPHER_SERVER_PREFERENCE"
 234 When choosing a cipher, use the server's preferences instead of the client
 235 preferences. When not set, the \s-1SSL\s0 server will always follow the clients
 236 preferences. When set, the \s-1SSL/TLS\s0 server will choose following its
 237 own preferences.
 238 .IP "SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_2, SSL_OP_NO_TLSv1_3, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2" 4
 239 .IX Item "SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_2, SSL_OP_NO_TLSv1_3, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2"
 240 These options turn off the SSLv3, TLSv1, TLSv1.1, TLSv1.2 or TLSv1.3 protocol
 241 versions with \s-1TLS\s0 or the DTLSv1, DTLSv1.2 versions with \s-1DTLS,\s0
 242 respectively.
 243 As of OpenSSL 1.1.0, these options are deprecated, use
 244 \&\fBSSL_CTX_set_min_proto_version\fR\|(3) and
 245 \&\fBSSL_CTX_set_max_proto_version\fR\|(3) instead.
 246 .IP "\s-1SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\s0" 4
 247 .IX Item "SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION"
 248 When performing renegotiation as a server, always start a new session
 249 (i.e., session resumption requests are only accepted in the initial
 250 handshake). This option is not needed for clients.
 251 .IP "\s-1SSL_OP_NO_COMPRESSION\s0" 4
 252 .IX Item "SSL_OP_NO_COMPRESSION"
 253 Do not use compression even if it is supported.
 254 .IP "\s-1SSL_OP_NO_QUERY_MTU\s0" 4
 255 .IX Item "SSL_OP_NO_QUERY_MTU"
 256 Do not query the \s-1MTU.\s0 Only affects \s-1DTLS\s0 connections.
 257 .IP "\s-1SSL_OP_COOKIE_EXCHANGE\s0" 4
 258 .IX Item "SSL_OP_COOKIE_EXCHANGE"
 259 Turn on Cookie Exchange as described in \s-1RFC4347\s0 Section 4.2.1. Only affects
 260 \&\s-1DTLS\s0 connections.
 261 .IP "\s-1SSL_OP_NO_TICKET\s0" 4
 262 .IX Item "SSL_OP_NO_TICKET"
 263 \&\s-1SSL/TLS\s0 supports two mechanisms for resuming sessions: session ids and stateless
 264 session tickets.
 265 .Sp
 266 When using session ids a copy of the session information is
 267 cached on the server and a unique id is sent to the client. When the client
 268 wishes to resume it provides the unique id so that the server can retrieve the
 269 session information from its cache.
 270 .Sp
 271 When using stateless session tickets the server uses a session ticket encryption
 272 key to encrypt the session information. This encrypted data is sent to the
 273 client as a \*(L"ticket\*(R". When the client wishes to resume it sends the encrypted
 274 data back to the server. The server uses its key to decrypt the data and resume
 275 the session. In this way the server can operate statelessly \- no session
 276 information needs to be cached locally.
 277 .Sp
 278 The TLSv1.3 protocol only supports tickets and does not directly support session
 279 ids. However, OpenSSL allows two modes of ticket operation in TLSv1.3: stateful
 280 and stateless. Stateless tickets work the same way as in TLSv1.2 and below.
 281 Stateful tickets mimic the session id behaviour available in TLSv1.2 and below.
 282 The session information is cached on the server and the session id is wrapped up
 283 in a ticket and sent back to the client. When the client wishes to resume, it
 284 presents a ticket in the same way as for stateless tickets. The server can then
 285 extract the session id from the ticket and retrieve the session information from
 286 its cache.
 287 .Sp
 288 By default OpenSSL will use stateless tickets. The \s-1SSL_OP_NO_TICKET\s0 option will
 289 cause stateless tickets to not be issued. In TLSv1.2 and below this means no
 290 ticket gets sent to the client at all. In TLSv1.3 a stateful ticket will be
 291 sent. This is a server-side option only.
 292 .Sp
 293 In TLSv1.3 it is possible to suppress all tickets (stateful and stateless) from
 294 being sent by calling \fBSSL_CTX_set_num_tickets\fR\|(3) or
 295 \&\fBSSL_set_num_tickets\fR\|(3).
 296 .IP "\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0" 4
 297 .IX Item "SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION"
 298 Allow legacy insecure renegotiation between OpenSSL and unpatched clients or
 299 servers. See the \fB\s-1SECURE RENEGOTIATION\s0\fR section for more details.
 300 .IP "\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0" 4
 301 .IX Item "SSL_OP_LEGACY_SERVER_CONNECT"
 302 Allow legacy insecure renegotiation between OpenSSL and unpatched servers
 303 \&\fBonly\fR: this option is currently set by default. See the
 304 \&\fB\s-1SECURE RENEGOTIATION\s0\fR section for more details.
 305 .IP "\s-1SSL_OP_NO_ENCRYPT_THEN_MAC\s0" 4
 306 .IX Item "SSL_OP_NO_ENCRYPT_THEN_MAC"
 307 Normally clients and servers will transparently attempt to negotiate the
 308 \&\s-1RFC7366\s0 Encrypt-then-MAC option on \s-1TLS\s0 and \s-1DTLS\s0 connection.
 309 .Sp
 310 If this option is set, Encrypt-then-MAC is disabled. Clients will not
 311 propose, and servers will not accept the extension.
 312 .IP "\s-1SSL_OP_NO_RENEGOTIATION\s0" 4
 313 .IX Item "SSL_OP_NO_RENEGOTIATION"
 314 Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest
 315 messages, and ignore renegotiation requests via ClientHello.
 316 .IP "\s-1SSL_OP_ALLOW_NO_DHE_KEX\s0" 4
 317 .IX Item "SSL_OP_ALLOW_NO_DHE_KEX"
 318 In TLSv1.3 allow a non\-(ec)dhe based key exchange mode on resumption. This means
 319 that there will be no forward secrecy for the resumed session.
 320 .IP "\s-1SSL_OP_PRIORITIZE_CHACHA\s0" 4
 321 .IX Item "SSL_OP_PRIORITIZE_CHACHA"
 322 When \s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0 is set, temporarily reprioritize
 323 ChaCha20\-Poly1305 ciphers to the top of the server cipher list if a
 324 ChaCha20\-Poly1305 cipher is at the top of the client cipher list. This helps
 325 those clients (e.g. mobile) use ChaCha20\-Poly1305 if that cipher is anywhere
 326 in the server cipher list; but still allows other clients to use \s-1AES\s0 and other
 327 ciphers. Requires \fB\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0\fR.
 328 .IP "\s-1SSL_OP_ENABLE_MIDDLEBOX_COMPAT\s0" 4
 329 .IX Item "SSL_OP_ENABLE_MIDDLEBOX_COMPAT"
 330 If set then dummy Change Cipher Spec (\s-1CCS\s0) messages are sent in TLSv1.3. This
 331 has the effect of making TLSv1.3 look more like TLSv1.2 so that middleboxes that
 332 do not understand TLSv1.3 will not drop the connection. Regardless of whether
 333 this option is set or not \s-1CCS\s0 messages received from the peer will always be
 334 ignored in TLSv1.3. This option is set by default. To switch it off use
 335 \&\fBSSL_clear_options()\fR. A future version of OpenSSL may not set this by default.
 336 .IP "\s-1SSL_OP_NO_ANTI_REPLAY\s0" 4
 337 .IX Item "SSL_OP_NO_ANTI_REPLAY"
 338 By default, when a server is configured for early data (i.e., max_early_data > 0),
 339 OpenSSL will switch on replay protection. See \fBSSL_read_early_data\fR\|(3) for a
 340 description of the replay protection feature. Anti-replay measures are required
 341 to comply with the TLSv1.3 specification. Some applications may be able to
 342 mitigate the replay risks in other ways and in such cases the built in OpenSSL
 343 functionality is not required. Those applications can turn this feature off by
 344 setting this option. This is a server-side opton only. It is ignored by
 345 clients.
 346 .PP
 347 The following options no longer have any effect but their identifiers are
 348 retained for compatibility purposes:
 349 .IP "\s-1SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG\s0" 4
 350 .IX Item "SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG"
 351 .PD 0
 352 .IP "\s-1SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER\s0" 4
 353 .IX Item "SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER"
 354 .IP "\s-1SSL_OP_SSLEAY_080_CLIENT_DH_BUG\s0" 4
 355 .IX Item "SSL_OP_SSLEAY_080_CLIENT_DH_BUG"
 356 .IP "\s-1SSL_OP_TLS_D5_BUG\s0" 4
 357 .IX Item "SSL_OP_TLS_D5_BUG"
 358 .IP "\s-1SSL_OP_TLS_BLOCK_PADDING_BUG\s0" 4
 359 .IX Item "SSL_OP_TLS_BLOCK_PADDING_BUG"
 360 .IP "\s-1SSL_OP_MSIE_SSLV2_RSA_PADDING\s0" 4
 361 .IX Item "SSL_OP_MSIE_SSLV2_RSA_PADDING"
 362 .IP "\s-1SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG\s0" 4
 363 .IX Item "SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG"
 364 .IP "\s-1SSL_OP_MICROSOFT_SESS_ID_BUG\s0" 4
 365 .IX Item "SSL_OP_MICROSOFT_SESS_ID_BUG"
 366 .IP "\s-1SSL_OP_NETSCAPE_CHALLENGE_BUG\s0" 4
 367 .IX Item "SSL_OP_NETSCAPE_CHALLENGE_BUG"
 368 .IP "\s-1SSL_OP_PKCS1_CHECK_1\s0" 4
 369 .IX Item "SSL_OP_PKCS1_CHECK_1"
 370 .IP "\s-1SSL_OP_PKCS1_CHECK_2\s0" 4
 371 .IX Item "SSL_OP_PKCS1_CHECK_2"
 372 .IP "\s-1SSL_OP_SINGLE_DH_USE\s0" 4
 373 .IX Item "SSL_OP_SINGLE_DH_USE"
 374 .IP "\s-1SSL_OP_SINGLE_ECDH_USE\s0" 4
 375 .IX Item "SSL_OP_SINGLE_ECDH_USE"
 376 .IP "\s-1SSL_OP_EPHEMERAL_RSA\s0" 4
 377 .IX Item "SSL_OP_EPHEMERAL_RSA"
 378 .PD
 379 .SH "SECURE RENEGOTIATION"
 380 .IX Header "SECURE RENEGOTIATION"
 381 OpenSSL always attempts to use secure renegotiation as
 382 described in \s-1RFC5746.\s0 This counters the prefix attack described in
 383 \&\s-1CVE\-2009\-3555\s0 and elsewhere.
 384 .PP
 385 This attack has far reaching consequences which application writers should be
 386 aware of. In the description below an implementation supporting secure
 387 renegotiation is referred to as \fIpatched\fR. A server not supporting secure
 388 renegotiation is referred to as \fIunpatched\fR.
 389 .PP
 390 The following sections describe the operations permitted by OpenSSL's secure
 391 renegotiation implementation.
 392 .SS "Patched client and server"
 393 .IX Subsection "Patched client and server"
 394 Connections and renegotiation are always permitted by OpenSSL implementations.
 395 .SS "Unpatched client and patched OpenSSL server"
 396 .IX Subsection "Unpatched client and patched OpenSSL server"
 397 The initial connection succeeds but client renegotiation is denied by the
 398 server with a \fBno_renegotiation\fR warning alert if \s-1TLS\s0 v1.0 is used or a fatal
 399 \&\fBhandshake_failure\fR alert in \s-1SSL\s0 v3.0.
 400 .PP
 401 If the patched OpenSSL server attempts to renegotiate a fatal
 402 \&\fBhandshake_failure\fR alert is sent. This is because the server code may be
 403 unaware of the unpatched nature of the client.
 404 .PP
 405 If the option \fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR is set then
 406 renegotiation \fBalways\fR succeeds.
 407 .SS "Patched OpenSSL client and unpatched server."
 408 .IX Subsection "Patched OpenSSL client and unpatched server."
 409 If the option \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR or
 410 \&\fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR is set then initial connections
 411 and renegotiation between patched OpenSSL clients and unpatched servers
 412 succeeds. If neither option is set then initial connections to unpatched
 413 servers will fail.
 414 .PP
 415 The option \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR is currently set by default even
 416 though it has security implications: otherwise it would be impossible to
 417 connect to unpatched servers (i.e. all of them initially) and this is clearly
 418 not acceptable. Renegotiation is permitted because this does not add any
 419 additional security issues: during an attack clients do not see any
 420 renegotiations anyway.
 421 .PP
 422 As more servers become patched the option \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR will
 423 \&\fBnot\fR be set by default in a future version of OpenSSL.
 424 .PP
 425 OpenSSL client applications wishing to ensure they can connect to unpatched
 426 servers should always \fBset\fR \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR
 427 .PP
 428 OpenSSL client applications that want to ensure they can \fBnot\fR connect to
 429 unpatched servers (and thus avoid any security issues) should always \fBclear\fR
 430 \&\fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR using \fBSSL_CTX_clear_options()\fR or
 431 \&\fBSSL_clear_options()\fR.
 432 .PP
 433 The difference between the \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR and
 434 \&\fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR options is that
 435 \&\fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR enables initial connections and secure
 436 renegotiation between OpenSSL clients and unpatched servers \fBonly\fR, while
 437 \&\fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR allows initial connections
 438 and renegotiation between OpenSSL and unpatched clients or servers.
 439 .SH "RETURN VALUES"
 440 .IX Header "RETURN VALUES"
 441 \&\fBSSL_CTX_set_options()\fR and \fBSSL_set_options()\fR return the new options bit mask
 442 after adding \fBoptions\fR.
 443 .PP
 444 \&\fBSSL_CTX_clear_options()\fR and \fBSSL_clear_options()\fR return the new options bit mask
 445 after clearing \fBoptions\fR.
 446 .PP
 447 \&\fBSSL_CTX_get_options()\fR and \fBSSL_get_options()\fR return the current bit mask.
 448 .PP
 449 \&\fBSSL_get_secure_renegotiation_support()\fR returns 1 is the peer supports
 450 secure renegotiation and 0 if it does not.
 451 .SH "SEE ALSO"
 452 .IX Header "SEE ALSO"
 453 \&\fBssl\fR\|(7), \fBSSL_new\fR\|(3), \fBSSL_clear\fR\|(3),
 454 \&\fBSSL_CTX_set_tmp_dh_callback\fR\|(3),
 455 \&\fBSSL_CTX_set_min_proto_version\fR\|(3),
 456 \&\fBdhparam\fR\|(1)
 457 .SH "HISTORY"
 458 .IX Header "HISTORY"
 459 The attempt to always try to use secure renegotiation was added in
 460 OpenSSL 0.9.8m.
 461 .PP
 462 The \fB\s-1SSL_OP_PRIORITIZE_CHACHA\s0\fR and \fB\s-1SSL_OP_NO_RENEGOTIATION\s0\fR options
 463 were added in OpenSSL 1.1.1.
 464 .SH "COPYRIGHT"
 465 .IX Header "COPYRIGHT"
 466 Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved.
 467 .PP
 468 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 469 this file except in compliance with the License.  You can obtain a copy
 470 in the file \s-1LICENSE\s0 in the source distribution or at
 471 <https://www.openssl.org/source/license.html>.