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