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 bitmask in B<options> to B<ctx>. 27Options already set before are not cleared! 28 29SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>. 30Options already set before are not cleared! 31 32SSL_CTX_clear_options() clears the options set via bitmask in B<options> 33to B<ctx>. 34 35SSL_clear_options() clears the options set via bitmask 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 bitmasks 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=back 241 242The following options no longer have any effect but their identifiers are 243retained for compatibility purposes: 244 245=over 4 246 247=item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG 248 249=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER 250 251=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG 252 253=item SSL_OP_TLS_D5_BUG 254 255=item SSL_OP_TLS_BLOCK_PADDING_BUG 256 257=item SSL_OP_MSIE_SSLV2_RSA_PADDING 258 259=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG 260 261=item SSL_OP_MICROSOFT_SESS_ID_BUG 262 263=item SSL_OP_NETSCAPE_CHALLENGE_BUG 264 265=item SSL_OP_PKCS1_CHECK_1 266 267=item SSL_OP_PKCS1_CHECK_2 268 269=item SSL_OP_SINGLE_DH_USE 270 271=item SSL_OP_SINGLE_ECDH_USE 272 273=item SSL_OP_EPHEMERAL_RSA 274 275=back 276 277=head1 SECURE RENEGOTIATION 278 279OpenSSL always attempts to use secure renegotiation as 280described in RFC5746. This counters the prefix attack described in 281CVE-2009-3555 and elsewhere. 282 283This attack has far reaching consequences which application writers should be 284aware of. In the description below an implementation supporting secure 285renegotiation is referred to as I<patched>. A server not supporting secure 286renegotiation is referred to as I<unpatched>. 287 288The following sections describe the operations permitted by OpenSSL's secure 289renegotiation implementation. 290 291=head2 Patched client and server 292 293Connections and renegotiation are always permitted by OpenSSL implementations. 294 295=head2 Unpatched client and patched OpenSSL server 296 297The initial connection succeeds but client renegotiation is denied by the 298server with a B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal 299B<handshake_failure> alert in SSL v3.0. 300 301If the patched OpenSSL server attempts to renegotiate a fatal 302B<handshake_failure> alert is sent. This is because the server code may be 303unaware of the unpatched nature of the client. 304 305If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then 306renegotiation B<always> succeeds. 307 308=head2 Patched OpenSSL client and unpatched server. 309 310If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or 311B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections 312and renegotiation between patched OpenSSL clients and unpatched servers 313succeeds. If neither option is set then initial connections to unpatched 314servers will fail. 315 316The option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even 317though it has security implications: otherwise it would be impossible to 318connect to unpatched servers (i.e. all of them initially) and this is clearly 319not acceptable. Renegotiation is permitted because this does not add any 320additional security issues: during an attack clients do not see any 321renegotiations anyway. 322 323As more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will 324B<not> be set by default in a future version of OpenSSL. 325 326OpenSSL client applications wishing to ensure they can connect to unpatched 327servers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT> 328 329OpenSSL client applications that want to ensure they can B<not> connect to 330unpatched servers (and thus avoid any security issues) should always B<clear> 331B<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or 332SSL_clear_options(). 333 334The difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and 335B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that 336B<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure 337renegotiation between OpenSSL clients and unpatched servers B<only>, while 338B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections 339and renegotiation between OpenSSL and unpatched clients or servers. 340 341=head1 RETURN VALUES 342 343SSL_CTX_set_options() and SSL_set_options() return the new options bitmask 344after adding B<options>. 345 346SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask 347after clearing B<options>. 348 349SSL_CTX_get_options() and SSL_get_options() return the current bitmask. 350 351SSL_get_secure_renegotiation_support() returns 1 is the peer supports 352secure renegotiation and 0 if it does not. 353 354=head1 SEE ALSO 355 356L<ssl(7)>, L<SSL_new(3)>, L<SSL_clear(3)>, 357L<SSL_CTX_set_tmp_dh_callback(3)>, 358L<SSL_CTX_set_min_proto_version(3)>, 359L<dhparam(1)> 360 361=head1 HISTORY 362 363The attempt to always try to use secure renegotiation was added in 364OpenSSL 0.9.8m. 365 366The B<SSL_OP_PRIORITIZE_CHACHA> and B<SSL_OP_NO_RENEGOTIATION> options 367were added in OpenSSL 1.1.1. 368 369=head1 COPYRIGHT 370 371Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved. 372 373Licensed under the OpenSSL license (the "License"). You may not use 374this file except in compliance with the License. You can obtain a copy 375in the file LICENSE in the source distribution or at 376L<https://www.openssl.org/source/license.html>. 377 378=cut 379