doc/man3/SSL_CTX_set_options.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options,
   6 SSL_clear_options, SSL_CTX_get_options, SSL_get_options,
   7 SSL_get_secure_renegotiation_support - manipulate SSL options
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/ssl.h>
  12
  13  long SSL_CTX_set_options(SSL_CTX *ctx, long options);
  14  long SSL_set_options(SSL *ssl, long options);
  15
  16  long SSL_CTX_clear_options(SSL_CTX *ctx, long options);
  17  long SSL_clear_options(SSL *ssl, long options);
  18
  19  long SSL_CTX_get_options(SSL_CTX *ctx);
  20  long SSL_get_options(SSL *ssl);
  21
  22  long SSL_get_secure_renegotiation_support(SSL *ssl);
  23
  24 =head1 DESCRIPTION
  25
  26 SSL_CTX_set_options() adds the options set via bit-mask in B<options> to B<ctx>.
  27 Options already set before are not cleared!
  28
  29 SSL_set_options() adds the options set via bit-mask in B<options> to B<ssl>.
  30 Options already set before are not cleared!
  31
  32 SSL_CTX_clear_options() clears the options set via bit-mask in B<options>
  33 to B<ctx>.
  34
  35 SSL_clear_options() clears the options set via bit-mask in B<options> to B<ssl>.
  36
  37 SSL_CTX_get_options() returns the options set for B<ctx>.
  38
  39 SSL_get_options() returns the options set for B<ssl>.
  40
  41 SSL_get_secure_renegotiation_support() indicates whether the peer supports
  42 secure renegotiation.
  43 Note, this is implemented via a macro.
  44
  45 =head1 NOTES
  46
  47 The behaviour of the SSL library can be changed by setting several options.
  48 The options are coded as bit-masks and can be combined by a bitwise B<or>
  49 operation (|).
  50
  51 SSL_CTX_set_options() and SSL_set_options() affect the (external)
  52 protocol behaviour of the SSL library. The (internal) behaviour of
  53 the API can be changed by using the similar
  54 L<SSL_CTX_set_mode(3)> and SSL_set_mode() functions.
  55
  56 During a handshake, the option settings of the SSL object are used. When
  57 a new SSL object is created from a context using SSL_new(), the current
  58 option setting is copied. Changes to B<ctx> do not affect already created
  59 SSL objects. SSL_clear() does not affect the settings.
  60
  61 The following B<bug workaround> options are available:
  62
  63 =over 4
  64
  65 =item SSL_OP_SAFARI_ECDHE_ECDSA_BUG
  66
  67 Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X.
  68 OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers.
  69
  70 =item SSL_OP_DISABLE_TLSEXT_CA_NAMES
  71
  72 Disable TLS Extension CA Names. You may want to disable it for security reasons
  73 or for compatibility with some Windows TLS implementations crashing when this
  74 extension is larger than 1024 bytes.
  75
  76 =item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
  77
  78 Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol
  79 vulnerability affecting CBC ciphers, which cannot be handled by some
  80 broken SSL implementations.  This option has no effect for connections
  81 using other ciphers.
  82
  83 =item SSL_OP_TLSEXT_PADDING
  84
  85 Adds a padding extension to ensure the ClientHello size is never between
  86 256 and 511 bytes in length. This is needed as a workaround for some
  87 implementations.
  88
  89 =item SSL_OP_ALL
  90
  91 All of the above bug workarounds plus B<SSL_OP_LEGACY_SERVER_CONNECT> as
  92 mentioned below.
  93
  94 =back
  95
  96 It is usually safe to use B<SSL_OP_ALL> to enable the bug workaround
  97 options if compatibility with somewhat broken implementations is
  98 desired.
  99
 100 The following B<modifying> options are available:
 101
 102 =over 4
 103
 104 =item SSL_OP_TLS_ROLLBACK_BUG
 105
 106 Disable version rollback attack detection.
 107
 108 During the client key exchange, the client must send the same information
 109 about acceptable SSL/TLS protocol levels as during the first hello. Some
 110 clients violate this rule by adapting to the server's answer. (Example:
 111 the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
 112 only understands up to SSLv3. In this case the client must still use the
 113 same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
 114 to the server's answer and violate the version rollback protection.)
 115
 116 =item SSL_OP_CIPHER_SERVER_PREFERENCE
 117
 118 When choosing a cipher, use the server's preferences instead of the client
 119 preferences. When not set, the SSL server will always follow the clients
 120 preferences. When set, the SSL/TLS server will choose following its
 121 own preferences.
 122
 123 =item SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1,
 124 SSL_OP_NO_TLSv1_2, SSL_OP_NO_TLSv1_3, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2
 125
 126 These options turn off the SSLv3, TLSv1, TLSv1.1, TLSv1.2 or TLSv1.3 protocol
 127 versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS,
 128 respectively.
 129 As of OpenSSL 1.1.0, these options are deprecated, use
 130 L<SSL_CTX_set_min_proto_version(3)> and
 131 L<SSL_CTX_set_max_proto_version(3)> instead.
 132
 133 =item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
 134
 135 When performing renegotiation as a server, always start a new session
 136 (i.e., session resumption requests are only accepted in the initial
 137 handshake). This option is not needed for clients.
 138
 139 =item SSL_OP_NO_COMPRESSION
 140
 141 Do not use compression even if it is supported.
 142
 143 =item SSL_OP_NO_QUERY_MTU
 144
 145 Do not query the MTU. Only affects DTLS connections.
 146
 147 =item SSL_OP_COOKIE_EXCHANGE
 148
 149 Turn on Cookie Exchange as described in RFC4347 Section 4.2.1. Only affects
 150 DTLS connections.
 151
 152 =item SSL_OP_NO_TICKET
 153
 154 SSL/TLS supports two mechanisms for resuming sessions: session ids and stateless
 155 session tickets.
 156
 157 When using session ids a copy of the session information is
 158 cached on the server and a unique id is sent to the client. When the client
 159 wishes to resume it provides the unique id so that the server can retrieve the
 160 session information from its cache.
 161
 162 When using stateless session tickets the server uses a session ticket encryption
 163 key to encrypt the session information. This encrypted data is sent to the
 164 client as a "ticket". When the client wishes to resume it sends the encrypted
 165 data back to the server. The server uses its key to decrypt the data and resume
 166 the session. In this way the server can operate statelessly - no session
 167 information needs to be cached locally.
 168
 169 The TLSv1.3 protocol only supports tickets and does not directly support session
 170 ids. However OpenSSL allows two modes of ticket operation in TLSv1.3: stateful
 171 and stateless. Stateless tickets work the same way as in TLSv1.2 and below.
 172 Stateful tickets mimic the session id behaviour available in TLSv1.2 and below.
 173 The session information is cached on the server and the session id is wrapped up
 174 in a ticket and sent back to the client. When the client wishes to resume, it
 175 presents a ticket in the same way as for stateless tickets. The server can then
 176 extract the session id from the ticket and retrieve the session information from
 177 its cache.
 178
 179 By default OpenSSL will use stateless tickets. The SSL_OP_NO_TICKET option will
 180 cause stateless tickets to not be issued. In TLSv1.2 and below this means no
 181 ticket gets sent to the client at all. In TLSv1.3 a stateful ticket will be
 182 sent. This is a server-side option only.
 183
 184 In TLSv1.3 it is possible to suppress all tickets (stateful and stateless) from
 185 being sent by calling L<SSL_CTX_set_num_tickets(3)> or
 186 L<SSL_set_num_tickets(3)>.
 187
 188 =item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
 189
 190 Allow legacy insecure renegotiation between OpenSSL and unpatched clients or
 191 servers. See the B<SECURE RENEGOTIATION> section for more details.
 192
 193 =item SSL_OP_LEGACY_SERVER_CONNECT
 194
 195 Allow legacy insecure renegotiation between OpenSSL and unpatched servers
 196 B<only>: this option is currently set by default. See the
 197 B<SECURE RENEGOTIATION> section for more details.
 198
 199 =item SSL_OP_NO_ENCRYPT_THEN_MAC
 200
 201 Normally clients and servers will transparently attempt to negotiate the
 202 RFC7366 Encrypt-then-MAC option on TLS and DTLS connection.
 203
 204 If this option is set, Encrypt-then-MAC is disabled. Clients will not
 205 propose, and servers will not accept the extension.
 206
 207 =item SSL_OP_NO_EXTENDED_MASTER_SECRET
 208
 209 Normally clients and servers will transparently attempt to negotiate the
 210 RFC7627 Extended Master Secret option on TLS and DTLS connection.
 211
 212 If this option is set, Extended Master Secret is disabled. Clients will
 213 not propose, and servers will not accept the extension.
 214
 215 =item SSL_OP_NO_RENEGOTIATION
 216
 217 Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest
 218 messages, and ignore renegotiation requests via ClientHello.
 219
 220 =item SSL_OP_IGNORE_UNEXPECTED_EOF
 221
 222 Some TLS implementations do not send the mandatory close_notify alert on
 223 shutdown. If the application tries to wait for the close_notify alert but the
 224 peer closes the connection without sending it, an error is generated. When this
 225 option is enabled the peer does not need to send the close_notify alert and a
 226 closed connection will be treated as if the close_notify alert was received.
 227
 228 You should only enable this option if the protocol running over TLS
 229 can detect a truncation attack itself, and that the application is checking for
 230 that truncation attack.
 231
 232 For more information on shutting down a connection, see L<SSL_shutdown(3)>.
 233
 234 =item SSL_OP_ALLOW_NO_DHE_KEX
 235
 236 In TLSv1.3 allow a non-(ec)dhe based key exchange mode on resumption. This means
 237 that there will be no forward secrecy for the resumed session.
 238
 239 =item SSL_OP_PRIORITIZE_CHACHA
 240
 241 When SSL_OP_CIPHER_SERVER_PREFERENCE is set, temporarily reprioritize
 242 ChaCha20-Poly1305 ciphers to the top of the server cipher list if a
 243 ChaCha20-Poly1305 cipher is at the top of the client cipher list. This helps
 244 those clients (e.g. mobile) use ChaCha20-Poly1305 if that cipher is anywhere
 245 in the server cipher list; but still allows other clients to use AES and other
 246 ciphers. Requires B<SSL_OP_CIPHER_SERVER_PREFERENCE>.
 247
 248 =item SSL_OP_ENABLE_MIDDLEBOX_COMPAT
 249
 250 If set then dummy Change Cipher Spec (CCS) messages are sent in TLSv1.3. This
 251 has the effect of making TLSv1.3 look more like TLSv1.2 so that middleboxes that
 252 do not understand TLSv1.3 will not drop the connection. Regardless of whether
 253 this option is set or not CCS messages received from the peer will always be
 254 ignored in TLSv1.3. This option is set by default. To switch it off use
 255 SSL_clear_options(). A future version of OpenSSL may not set this by default.
 256
 257 =item SSL_OP_NO_ANTI_REPLAY
 258
 259 By default, when a server is configured for early data (i.e., max_early_data > 0),
 260 OpenSSL will switch on replay protection. See L<SSL_read_early_data(3)> for a
 261 description of the replay protection feature. Anti-replay measures are required
 262 to comply with the TLSv1.3 specification. Some applications may be able to
 263 mitigate the replay risks in other ways and in such cases the built in OpenSSL
 264 functionality is not required. Those applications can turn this feature off by
 265 setting this option. This is a server-side opton only. It is ignored by
 266 clients.
 267
 268 =back
 269
 270 The following options no longer have any effect but their identifiers are
 271 retained for compatibility purposes:
 272
 273 =over 4
 274
 275 =item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
 276
 277 =item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
 278
 279 =item SSL_OP_SSLEAY_080_CLIENT_DH_BUG
 280
 281 =item SSL_OP_TLS_D5_BUG
 282
 283 =item SSL_OP_TLS_BLOCK_PADDING_BUG
 284
 285 =item SSL_OP_MSIE_SSLV2_RSA_PADDING
 286
 287 =item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
 288
 289 =item SSL_OP_MICROSOFT_SESS_ID_BUG
 290
 291 =item SSL_OP_NETSCAPE_CHALLENGE_BUG
 292
 293 =item SSL_OP_PKCS1_CHECK_1
 294
 295 =item SSL_OP_PKCS1_CHECK_2
 296
 297 =item SSL_OP_SINGLE_DH_USE
 298
 299 =item SSL_OP_SINGLE_ECDH_USE
 300
 301 =item SSL_OP_EPHEMERAL_RSA
 302
 303 =back
 304
 305 =head1 SECURE RENEGOTIATION
 306
 307 OpenSSL always attempts to use secure renegotiation as
 308 described in RFC5746. This counters the prefix attack described in
 309 CVE-2009-3555 and elsewhere.
 310
 311 This attack has far reaching consequences which application writers should be
 312 aware of. In the description below an implementation supporting secure
 313 renegotiation is referred to as I<patched>. A server not supporting secure
 314 renegotiation is referred to as I<unpatched>.
 315
 316 The following sections describe the operations permitted by OpenSSL's secure
 317 renegotiation implementation.
 318
 319 =head2 Patched client and server
 320
 321 Connections and renegotiation are always permitted by OpenSSL implementations.
 322
 323 =head2 Unpatched client and patched OpenSSL server
 324
 325 The initial connection succeeds but client renegotiation is denied by the
 326 server with a B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal
 327 B<handshake_failure> alert in SSL v3.0.
 328
 329 If the patched OpenSSL server attempts to renegotiate a fatal
 330 B<handshake_failure> alert is sent. This is because the server code may be
 331 unaware of the unpatched nature of the client.
 332
 333 If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then
 334 renegotiation B<always> succeeds.
 335
 336 =head2 Patched OpenSSL client and unpatched server
 337
 338 If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or
 339 B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections
 340 and renegotiation between patched OpenSSL clients and unpatched servers
 341 succeeds. If neither option is set then initial connections to unpatched
 342 servers will fail.
 343
 344 The option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even
 345 though it has security implications: otherwise it would be impossible to
 346 connect to unpatched servers (i.e. all of them initially) and this is clearly
 347 not acceptable. Renegotiation is permitted because this does not add any
 348 additional security issues: during an attack clients do not see any
 349 renegotiations anyway.
 350
 351 As more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will
 352 B<not> be set by default in a future version of OpenSSL.
 353
 354 OpenSSL client applications wishing to ensure they can connect to unpatched
 355 servers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT>
 356
 357 OpenSSL client applications that want to ensure they can B<not> connect to
 358 unpatched servers (and thus avoid any security issues) should always B<clear>
 359 B<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or
 360 SSL_clear_options().
 361
 362 The difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and
 363 B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that
 364 B<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure
 365 renegotiation between OpenSSL clients and unpatched servers B<only>, while
 366 B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections
 367 and renegotiation between OpenSSL and unpatched clients or servers.
 368
 369 =head1 RETURN VALUES
 370
 371 SSL_CTX_set_options() and SSL_set_options() return the new options bit-mask
 372 after adding B<options>.
 373
 374 SSL_CTX_clear_options() and SSL_clear_options() return the new options bit-mask
 375 after clearing B<options>.
 376
 377 SSL_CTX_get_options() and SSL_get_options() return the current bit-mask.
 378
 379 SSL_get_secure_renegotiation_support() returns 1 is the peer supports
 380 secure renegotiation and 0 if it does not.
 381
 382 =head1 SEE ALSO
 383
 384 L<ssl(7)>, L<SSL_new(3)>, L<SSL_clear(3)>, L<SSL_shutdown(3)>
 385 L<SSL_CTX_set_tmp_dh_callback(3)>,
 386 L<SSL_CTX_set_min_proto_version(3)>,
 387 L<openssl-dhparam(1)>
 388
 389 =head1 HISTORY
 390
 391 The attempt to always try to use secure renegotiation was added in
 392 OpenSSL 0.9.8m.
 393
 394 The B<SSL_OP_PRIORITIZE_CHACHA> and B<SSL_OP_NO_RENEGOTIATION> options
 395 were added in OpenSSL 1.1.1.
 396
 397 The B<SSL_OP_NO_EXTENDED_MASTER_SECRET> and B<SSL_OP_IGNORE_UNEXPECTED_EOF>
 398 options were added in OpenSSL 3.0.
 399
 400 =head1 COPYRIGHT
 401
 402 Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved.
 403
 404 Licensed under the Apache License 2.0 (the "License").  You may not use
 405 this file except in compliance with the License.  You can obtain a copy
 406 in the file LICENSE in the source distribution or at
 407 L<https://www.openssl.org/source/license.html>.
 408
 409 =cut