secure/lib/libcrypto/man/SSL_CTX_set_options.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_CTX_SET_OPTIONS 3"
 132 .TH SSL_CTX_SET_OPTIONS 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& long SSL_CTX_set_options(SSL_CTX *ctx, long options);
 145 \& long SSL_set_options(SSL *ssl, long options);
 146 \&
 147 \& long SSL_CTX_clear_options(SSL_CTX *ctx, long options);
 148 \& long SSL_clear_options(SSL *ssl, long options);
 149 \&
 150 \& long SSL_CTX_get_options(SSL_CTX *ctx);
 151 \& long SSL_get_options(SSL *ssl);
 152 \&
 153 \& long SSL_get_secure_renegotiation_support(SSL *ssl);
 154 .Ve
 155 .SH "DESCRIPTION"
 156 .IX Header "DESCRIPTION"
 157 \&\fISSL_CTX_set_options()\fR adds the options set via bitmask in \fBoptions\fR to \fBctx\fR.
 158 Options already set before are not cleared!
 159 .PP
 160 \&\fISSL_set_options()\fR adds the options set via bitmask in \fBoptions\fR to \fBssl\fR.
 161 Options already set before are not cleared!
 162 .PP
 163 \&\fISSL_CTX_clear_options()\fR clears the options set via bitmask in \fBoptions\fR
 164 to \fBctx\fR.
 165 .PP
 166 \&\fISSL_clear_options()\fR clears the options set via bitmask in \fBoptions\fR to \fBssl\fR.
 167 .PP
 168 \&\fISSL_CTX_get_options()\fR returns the options set for \fBctx\fR.
 169 .PP
 170 \&\fISSL_get_options()\fR returns the options set for \fBssl\fR.
 171 .PP
 172 \&\fISSL_get_secure_renegotiation_support()\fR indicates whether the peer supports
 173 secure renegotiation.
 174 Note, this is implemented via a macro.
 175 .SH "NOTES"
 176 .IX Header "NOTES"
 177 The behaviour of the \s-1SSL\s0 library can be changed by setting several options.
 178 The options are coded as bitmasks and can be combined by a bitwise \fBor\fR
 179 operation (|).
 180 .PP
 181 \&\fISSL_CTX_set_options()\fR and \fISSL_set_options()\fR affect the (external)
 182 protocol behaviour of the \s-1SSL\s0 library. The (internal) behaviour of
 183 the \s-1API\s0 can be changed by using the similar
 184 \&\fISSL_CTX_set_mode\fR\|(3) and \fISSL_set_mode()\fR functions.
 185 .PP
 186 During a handshake, the option settings of the \s-1SSL\s0 object are used. When
 187 a new \s-1SSL\s0 object is created from a context using \fISSL_new()\fR, the current
 188 option setting is copied. Changes to \fBctx\fR do not affect already created
 189 \&\s-1SSL\s0 objects. \fISSL_clear()\fR does not affect the settings.
 190 .PP
 191 The following \fBbug workaround\fR options are available:
 192 .IP "\s-1SSL_OP_SAFARI_ECDHE_ECDSA_BUG\s0" 4
 193 .IX Item "SSL_OP_SAFARI_ECDHE_ECDSA_BUG"
 194 Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on \s-1OS X.
 195 OS X 10.8..10.8.3\s0 has broken support for ECDHE-ECDSA ciphers.
 196 .IP "\s-1SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS\s0" 4
 197 .IX Item "SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS"
 198 Disables a countermeasure against a \s-1SSL 3.0/TLS 1.0\s0 protocol
 199 vulnerability affecting \s-1CBC\s0 ciphers, which cannot be handled by some
 200 broken \s-1SSL\s0 implementations.  This option has no effect for connections
 201 using other ciphers.
 202 .IP "\s-1SSL_OP_TLSEXT_PADDING\s0" 4
 203 .IX Item "SSL_OP_TLSEXT_PADDING"
 204 Adds a padding extension to ensure the ClientHello size is never between
 205 256 and 511 bytes in length. This is needed as a workaround for some
 206 implementations.
 207 .IP "\s-1SSL_OP_ALL\s0" 4
 208 .IX Item "SSL_OP_ALL"
 209 All of the above bug workarounds plus \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR as
 210 mentioned below.
 211 .PP
 212 It is usually safe to use \fB\s-1SSL_OP_ALL\s0\fR to enable the bug workaround
 213 options if compatibility with somewhat broken implementations is
 214 desired.
 215 .PP
 216 The following \fBmodifying\fR options are available:
 217 .IP "\s-1SSL_OP_TLS_ROLLBACK_BUG\s0" 4
 218 .IX Item "SSL_OP_TLS_ROLLBACK_BUG"
 219 Disable version rollback attack detection.
 220 .Sp
 221 During the client key exchange, the client must send the same information
 222 about acceptable \s-1SSL/TLS\s0 protocol levels as during the first hello. Some
 223 clients violate this rule by adapting to the server's answer. (Example:
 224 the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
 225 only understands up to SSLv3. In this case the client must still use the
 226 same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
 227 to the server's answer and violate the version rollback protection.)
 228 .IP "\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0" 4
 229 .IX Item "SSL_OP_CIPHER_SERVER_PREFERENCE"
 230 When choosing a cipher, use the server's preferences instead of the client
 231 preferences. When not set, the \s-1SSL\s0 server will always follow the clients
 232 preferences. When set, the \s-1SSL/TLS\s0 server will choose following its
 233 own preferences.
 234 .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
 235 .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"
 236 These options turn off the SSLv3, TLSv1, TLSv1.1, TLSv1.2 or TLSv1.3 protocol
 237 versions with \s-1TLS\s0 or the DTLSv1, DTLSv1.2 versions with \s-1DTLS,\s0
 238 respectively.
 239 As of OpenSSL 1.1.0, these options are deprecated, use
 240 \&\fISSL_CTX_set_min_proto_version\fR\|(3) and
 241 \&\fISSL_CTX_set_max_proto_version\fR\|(3) instead.
 242 .IP "\s-1SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\s0" 4
 243 .IX Item "SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION"
 244 When performing renegotiation as a server, always start a new session
 245 (i.e., session resumption requests are only accepted in the initial
 246 handshake). This option is not needed for clients.
 247 .IP "\s-1SSL_OP_NO_COMPRESSION\s0" 4
 248 .IX Item "SSL_OP_NO_COMPRESSION"
 249 Do not use compression even if it is supported.
 250 .IP "\s-1SSL_OP_NO_QUERY_MTU\s0" 4
 251 .IX Item "SSL_OP_NO_QUERY_MTU"
 252 Do not query the \s-1MTU.\s0 Only affects \s-1DTLS\s0 connections.
 253 .IP "\s-1SSL_OP_COOKIE_EXCHANGE\s0" 4
 254 .IX Item "SSL_OP_COOKIE_EXCHANGE"
 255 Turn on Cookie Exchange as described in \s-1RFC4347\s0 Section 4.2.1. Only affects
 256 \&\s-1DTLS\s0 connections.
 257 .IP "\s-1SSL_OP_NO_TICKET\s0" 4
 258 .IX Item "SSL_OP_NO_TICKET"
 259 \&\s-1SSL/TLS\s0 supports two mechanisms for resuming sessions: session ids and stateless
 260 session tickets.
 261 .Sp
 262 When using session ids a copy of the session information is
 263 cached on the server and a unique id is sent to the client. When the client
 264 wishes to resume it provides the unique id so that the server can retrieve the
 265 session information from its cache.
 266 .Sp
 267 When using stateless session tickets the server uses a session ticket encryption
 268 key to encrypt the session information. This encrypted data is sent to the
 269 client as a \*(L"ticket\*(R". When the client wishes to resume it sends the encrypted
 270 data back to the server. The server uses its key to decrypt the data and resume
 271 the session. In this way the server can operate statelessly \- no session
 272 information needs to be cached locally.
 273 .Sp
 274 The TLSv1.3 protocol only supports tickets and does not directly support session
 275 ids. However OpenSSL allows two modes of ticket operation in TLSv1.3: stateful
 276 and stateless. Stateless tickets work the same way as in TLSv1.2 and below.
 277 Stateful tickets mimic the session id behaviour available in TLSv1.2 and below.
 278 The session information is cached on the server and the session id is wrapped up
 279 in a ticket and sent back to the client. When the client wishes to resume, it
 280 presents a ticket in the same way as for stateless tickets. The server can then
 281 extract the session id from the ticket and retrieve the session information from
 282 its cache.
 283 .Sp
 284 By default OpenSSL will use stateless tickets. The \s-1SSL_OP_NO_TICKET\s0 option will
 285 cause stateless tickets to not be issued. In TLSv1.2 and below this means no
 286 ticket gets sent to the client at all. In TLSv1.3 a stateful ticket will be
 287 sent. This is a server-side option only.
 288 .Sp
 289 In TLSv1.3 it is possible to suppress all tickets (stateful and stateless) from
 290 being sent by calling \fISSL_CTX_set_num_tickets\fR\|(3) or
 291 \&\fISSL_set_num_tickets\fR\|(3).
 292 .IP "\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0" 4
 293 .IX Item "SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION"
 294 Allow legacy insecure renegotiation between OpenSSL and unpatched clients or
 295 servers. See the \fB\s-1SECURE RENEGOTIATION\s0\fR section for more details.
 296 .IP "\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0" 4
 297 .IX Item "SSL_OP_LEGACY_SERVER_CONNECT"
 298 Allow legacy insecure renegotiation between OpenSSL and unpatched servers
 299 \&\fBonly\fR: this option is currently set by default. See the
 300 \&\fB\s-1SECURE RENEGOTIATION\s0\fR section for more details.
 301 .IP "\s-1SSL_OP_NO_ENCRYPT_THEN_MAC\s0" 4
 302 .IX Item "SSL_OP_NO_ENCRYPT_THEN_MAC"
 303 Normally clients and servers will transparently attempt to negotiate the
 304 \&\s-1RFC7366\s0 Encrypt-then-MAC option on \s-1TLS\s0 and \s-1DTLS\s0 connection.
 305 .Sp
 306 If this option is set, Encrypt-then-MAC is disabled. Clients will not
 307 propose, and servers will not accept the extension.
 308 .IP "\s-1SSL_OP_NO_RENEGOTIATION\s0" 4
 309 .IX Item "SSL_OP_NO_RENEGOTIATION"
 310 Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest
 311 messages, and ignore renegotiation requests via ClientHello.
 312 .IP "\s-1SSL_OP_ALLOW_NO_DHE_KEX\s0" 4
 313 .IX Item "SSL_OP_ALLOW_NO_DHE_KEX"
 314 In TLSv1.3 allow a non\-(ec)dhe based key exchange mode on resumption. This means
 315 that there will be no forward secrecy for the resumed session.
 316 .IP "\s-1SSL_OP_PRIORITIZE_CHACHA\s0" 4
 317 .IX Item "SSL_OP_PRIORITIZE_CHACHA"
 318 When \s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0 is set, temporarily reprioritize
 319 ChaCha20\-Poly1305 ciphers to the top of the server cipher list if a
 320 ChaCha20\-Poly1305 cipher is at the top of the client cipher list. This helps
 321 those clients (e.g. mobile) use ChaCha20\-Poly1305 if that cipher is anywhere
 322 in the server cipher list; but still allows other clients to use \s-1AES\s0 and other
 323 ciphers. Requires \fB\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0\fR.
 324 .IP "\s-1SSL_OP_ENABLE_MIDDLEBOX_COMPAT\s0" 4
 325 .IX Item "SSL_OP_ENABLE_MIDDLEBOX_COMPAT"
 326 If set then dummy Change Cipher Spec (\s-1CCS\s0) messages are sent in TLSv1.3. This
 327 has the effect of making TLSv1.3 look more like TLSv1.2 so that middleboxes that
 328 do not understand TLSv1.3 will not drop the connection. Regardless of whether
 329 this option is set or not \s-1CCS\s0 messages received from the peer will always be
 330 ignored in TLSv1.3. This option is set by default. To switch it off use
 331 \&\fISSL_clear_options()\fR. A future version of OpenSSL may not set this by default.
 332 .IP "\s-1SSL_OP_NO_ANTI_REPLAY\s0" 4
 333 .IX Item "SSL_OP_NO_ANTI_REPLAY"
 334 By default, when a server is configured for early data (i.e., max_early_data > 0),
 335 OpenSSL will switch on replay protection. See \fISSL_read_early_data\fR\|(3) for a
 336 description of the replay protection feature. Anti-replay measures are required
 337 to comply with the TLSv1.3 specification. Some applications may be able to
 338 mitigate the replay risks in other ways and in such cases the built in OpenSSL
 339 functionality is not required. Those applications can turn this feature off by
 340 setting this option. This is a server-side opton only. It is ignored by
 341 clients.
 342 .PP
 343 The following options no longer have any effect but their identifiers are
 344 retained for compatibility purposes:
 345 .IP "\s-1SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG\s0" 4
 346 .IX Item "SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG"
 347 .PD 0
 348 .IP "\s-1SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER\s0" 4
 349 .IX Item "SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER"
 350 .IP "\s-1SSL_OP_SSLEAY_080_CLIENT_DH_BUG\s0" 4
 351 .IX Item "SSL_OP_SSLEAY_080_CLIENT_DH_BUG"
 352 .IP "\s-1SSL_OP_TLS_D5_BUG\s0" 4
 353 .IX Item "SSL_OP_TLS_D5_BUG"
 354 .IP "\s-1SSL_OP_TLS_BLOCK_PADDING_BUG\s0" 4
 355 .IX Item "SSL_OP_TLS_BLOCK_PADDING_BUG"
 356 .IP "\s-1SSL_OP_MSIE_SSLV2_RSA_PADDING\s0" 4
 357 .IX Item "SSL_OP_MSIE_SSLV2_RSA_PADDING"
 358 .IP "\s-1SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG\s0" 4
 359 .IX Item "SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG"
 360 .IP "\s-1SSL_OP_MICROSOFT_SESS_ID_BUG\s0" 4
 361 .IX Item "SSL_OP_MICROSOFT_SESS_ID_BUG"
 362 .IP "\s-1SSL_OP_NETSCAPE_CHALLENGE_BUG\s0" 4
 363 .IX Item "SSL_OP_NETSCAPE_CHALLENGE_BUG"
 364 .IP "\s-1SSL_OP_PKCS1_CHECK_1\s0" 4
 365 .IX Item "SSL_OP_PKCS1_CHECK_1"
 366 .IP "\s-1SSL_OP_PKCS1_CHECK_2\s0" 4
 367 .IX Item "SSL_OP_PKCS1_CHECK_2"
 368 .IP "\s-1SSL_OP_SINGLE_DH_USE\s0" 4
 369 .IX Item "SSL_OP_SINGLE_DH_USE"
 370 .IP "\s-1SSL_OP_SINGLE_ECDH_USE\s0" 4
 371 .IX Item "SSL_OP_SINGLE_ECDH_USE"
 372 .IP "\s-1SSL_OP_EPHEMERAL_RSA\s0" 4
 373 .IX Item "SSL_OP_EPHEMERAL_RSA"
 374 .PD
 375 .SH "SECURE RENEGOTIATION"
 376 .IX Header "SECURE RENEGOTIATION"
 377 OpenSSL always attempts to use secure renegotiation as
 378 described in \s-1RFC5746.\s0 This counters the prefix attack described in
 379 \&\s-1CVE\-2009\-3555\s0 and elsewhere.
 380 .PP
 381 This attack has far reaching consequences which application writers should be
 382 aware of. In the description below an implementation supporting secure
 383 renegotiation is referred to as \fIpatched\fR. A server not supporting secure
 384 renegotiation is referred to as \fIunpatched\fR.
 385 .PP
 386 The following sections describe the operations permitted by OpenSSL's secure
 387 renegotiation implementation.
 388 .SS "Patched client and server"
 389 .IX Subsection "Patched client and server"
 390 Connections and renegotiation are always permitted by OpenSSL implementations.
 391 .SS "Unpatched client and patched OpenSSL server"
 392 .IX Subsection "Unpatched client and patched OpenSSL server"
 393 The initial connection succeeds but client renegotiation is denied by the
 394 server with a \fBno_renegotiation\fR warning alert if \s-1TLS\s0 v1.0 is used or a fatal
 395 \&\fBhandshake_failure\fR alert in \s-1SSL\s0 v3.0.
 396 .PP
 397 If the patched OpenSSL server attempts to renegotiate a fatal
 398 \&\fBhandshake_failure\fR alert is sent. This is because the server code may be
 399 unaware of the unpatched nature of the client.
 400 .PP
 401 If the option \fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR is set then
 402 renegotiation \fBalways\fR succeeds.
 403 .SS "Patched OpenSSL client and unpatched server."
 404 .IX Subsection "Patched OpenSSL client and unpatched server."
 405 If the option \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR or
 406 \&\fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR is set then initial connections
 407 and renegotiation between patched OpenSSL clients and unpatched servers
 408 succeeds. If neither option is set then initial connections to unpatched
 409 servers will fail.
 410 .PP
 411 The option \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR is currently set by default even
 412 though it has security implications: otherwise it would be impossible to
 413 connect to unpatched servers (i.e. all of them initially) and this is clearly
 414 not acceptable. Renegotiation is permitted because this does not add any
 415 additional security issues: during an attack clients do not see any
 416 renegotiations anyway.
 417 .PP
 418 As more servers become patched the option \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR will
 419 \&\fBnot\fR be set by default in a future version of OpenSSL.
 420 .PP
 421 OpenSSL client applications wishing to ensure they can connect to unpatched
 422 servers should always \fBset\fR \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR
 423 .PP
 424 OpenSSL client applications that want to ensure they can \fBnot\fR connect to
 425 unpatched servers (and thus avoid any security issues) should always \fBclear\fR
 426 \&\fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR using \fISSL_CTX_clear_options()\fR or
 427 \&\fISSL_clear_options()\fR.
 428 .PP
 429 The difference between the \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR and
 430 \&\fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR options is that
 431 \&\fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR enables initial connections and secure
 432 renegotiation between OpenSSL clients and unpatched servers \fBonly\fR, while
 433 \&\fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR allows initial connections
 434 and renegotiation between OpenSSL and unpatched clients or servers.
 435 .SH "RETURN VALUES"
 436 .IX Header "RETURN VALUES"
 437 \&\fISSL_CTX_set_options()\fR and \fISSL_set_options()\fR return the new options bitmask
 438 after adding \fBoptions\fR.
 439 .PP
 440 \&\fISSL_CTX_clear_options()\fR and \fISSL_clear_options()\fR return the new options bitmask
 441 after clearing \fBoptions\fR.
 442 .PP
 443 \&\fISSL_CTX_get_options()\fR and \fISSL_get_options()\fR return the current bitmask.
 444 .PP
 445 \&\fISSL_get_secure_renegotiation_support()\fR returns 1 is the peer supports
 446 secure renegotiation and 0 if it does not.
 447 .SH "SEE ALSO"
 448 .IX Header "SEE ALSO"
 449 \&\fIssl\fR\|(7), \fISSL_new\fR\|(3), \fISSL_clear\fR\|(3),
 450 \&\fISSL_CTX_set_tmp_dh_callback\fR\|(3),
 451 \&\fISSL_CTX_set_min_proto_version\fR\|(3),
 452 \&\fIdhparam\fR\|(1)
 453 .SH "HISTORY"
 454 .IX Header "HISTORY"
 455 The attempt to always try to use secure renegotiation was added in
 456 Openssl 0.9.8m.
 457 .PP
 458 \&\fB\s-1SSL_OP_PRIORITIZE_CHACHA\s0\fR and \fB\s-1SSL_OP_NO_RENEGOTIATION\s0\fR were added in
 459 OpenSSL 1.1.1.
 460 .SH "COPYRIGHT"
 461 .IX Header "COPYRIGHT"
 462 Copyright 2001\-2018 The OpenSSL Project Authors. All Rights Reserved.
 463 .PP
 464 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 465 this file except in compliance with the License.  You can obtain a copy
 466 in the file \s-1LICENSE\s0 in the source distribution or at
 467 <https://www.openssl.org/source/license.html>.