172613Skris=pod 272613Skris 372613Skris=head1 NAME 472613Skris 5205128SsimonSSL_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 672613Skris 772613Skris=head1 SYNOPSIS 872613Skris 972613Skris #include <openssl/ssl.h> 1072613Skris 1172613Skris long SSL_CTX_set_options(SSL_CTX *ctx, long options); 1272613Skris long SSL_set_options(SSL *ssl, long options); 1372613Skris 14205128Ssimon long SSL_CTX_clear_options(SSL_CTX *ctx, long options); 15205128Ssimon long SSL_clear_options(SSL *ssl, long options); 16205128Ssimon 1772613Skris long SSL_CTX_get_options(SSL_CTX *ctx); 1872613Skris long SSL_get_options(SSL *ssl); 1972613Skris 20205128Ssimon long SSL_get_secure_renegotiation_support(SSL *ssl); 21205128Ssimon 2272613Skris=head1 DESCRIPTION 2372613Skris 24205128SsimonNote: all these functions are implemented using macros. 25205128Ssimon 2672613SkrisSSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>. 2789837SkrisOptions already set before are not cleared! 2872613Skris 2972613SkrisSSL_set_options() adds the options set via bitmask in B<options> to B<ssl>. 3089837SkrisOptions already set before are not cleared! 3172613Skris 32205128SsimonSSL_CTX_clear_options() clears the options set via bitmask in B<options> 33205128Ssimonto B<ctx>. 34205128Ssimon 35205128SsimonSSL_clear_options() clears the options set via bitmask in B<options> to B<ssl>. 36205128Ssimon 3772613SkrisSSL_CTX_get_options() returns the options set for B<ctx>. 3872613Skris 3972613SkrisSSL_get_options() returns the options set for B<ssl>. 4072613Skris 41205128SsimonSSL_get_secure_renegotiation_support() indicates whether the peer supports 42205128Ssimonsecure renegotiation. 43205128Ssimon 4472613Skris=head1 NOTES 4572613Skris 4672613SkrisThe behaviour of the SSL library can be changed by setting several options. 4772613SkrisThe options are coded as bitmasks and can be combined by a logical B<or> 48205128Ssimonoperation (|). 4972613Skris 5089837SkrisSSL_CTX_set_options() and SSL_set_options() affect the (external) 5189837Skrisprotocol behaviour of the SSL library. The (internal) behaviour of 5289837Skristhe API can be changed by using the similar 53100936SnectarL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> and SSL_set_mode() functions. 5489837Skris 5589837SkrisDuring a handshake, the option settings of the SSL object are used. When 5672613Skrisa new SSL object is created from a context using SSL_new(), the current 5772613Skrisoption setting is copied. Changes to B<ctx> do not affect already created 5872613SkrisSSL objects. SSL_clear() does not affect the settings. 5972613Skris 6072613SkrisThe following B<bug workaround> options are available: 6172613Skris 6272613Skris=over 4 6372613Skris 6472613Skris=item SSL_OP_MICROSOFT_SESS_ID_BUG 6572613Skris 6672613Skriswww.microsoft.com - when talking SSLv2, if session-id reuse is 6772613Skrisperformed, the session-id passed back in the server-finished message 6872613Skrisis different from the one decided upon. 6972613Skris 7072613Skris=item SSL_OP_NETSCAPE_CHALLENGE_BUG 7172613Skris 7272613SkrisNetscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte 7372613Skrischallenge but then appears to only use 16 bytes when generating the 7472613Skrisencryption keys. Using 16 bytes is ok but it should be ok to use 32. 7572613SkrisAccording to the SSLv3 spec, one should use 32 bytes for the challenge 7676866Skriswhen operating in SSLv2/v3 compatibility mode, but as mentioned above, 7772613Skristhis breaks this server so 16 bytes is the way to go. 7872613Skris 7972613Skris=item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG 8072613Skris 81216166SsimonAs of OpenSSL 0.9.8q and 1.0.0c, this option has no effect. 8272613Skris 8372613Skris=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG 8472613Skris 8572613Skris... 8672613Skris 8772613Skris=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER 8872613Skris 8972613Skris... 9072613Skris 91267285Sjkim=item SSL_OP_SAFARI_ECDHE_ECDSA_BUG 9272613Skris 93267285SjkimDon't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X. 94267285SjkimOS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers. 9572613Skris 9672613Skris=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG 9772613Skris 9872613Skris... 9972613Skris 10072613Skris=item SSL_OP_TLS_D5_BUG 10172613Skris 10272613Skris... 10372613Skris 10472613Skris=item SSL_OP_TLS_BLOCK_PADDING_BUG 10572613Skris 10672613Skris... 10772613Skris 108100936Snectar=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS 109100936Snectar 110100936SnectarDisables a countermeasure against a SSL 3.0/TLS 1.0 protocol 111100936Snectarvulnerability affecting CBC ciphers, which cannot be handled by some 112100936Snectarbroken SSL implementations. This option has no effect for connections 113100936Snectarusing other ciphers. 114100936Snectar 11572613Skris=item SSL_OP_ALL 11672613Skris 11772613SkrisAll of the above bug workarounds. 11872613Skris 11972613Skris=back 12072613Skris 121100936SnectarIt is usually safe to use B<SSL_OP_ALL> to enable the bug workaround 122100936Snectaroptions if compatibility with somewhat broken implementations is 123100936Snectardesired. 12472613Skris 12572613SkrisThe following B<modifying> options are available: 12672613Skris 12772613Skris=over 4 12872613Skris 129109998Smarkm=item SSL_OP_TLS_ROLLBACK_BUG 130109998Smarkm 131109998SmarkmDisable version rollback attack detection. 132109998Smarkm 133109998SmarkmDuring the client key exchange, the client must send the same information 134109998Smarkmabout acceptable SSL/TLS protocol levels as during the first hello. Some 135109998Smarkmclients violate this rule by adapting to the server's answer. (Example: 136109998Smarkmthe client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server 137109998Smarkmonly understands up to SSLv3. In this case the client must still use the 138109998Smarkmsame SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect 139109998Smarkmto the server's answer and violate the version rollback protection.) 140109998Smarkm 14172613Skris=item SSL_OP_SINGLE_DH_USE 14272613Skris 14389837SkrisAlways create a new key when using temporary/ephemeral DH parameters 14489837Skris(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>). 14589837SkrisThis option must be used to prevent small subgroup attacks, when 14689837Skristhe DH parameters were not generated using "strong" primes 14789837Skris(e.g. when using DSA-parameters, see L<dhparam(1)|dhparam(1)>). 14889837SkrisIf "strong" primes were used, it is not strictly necessary to generate 14989837Skrisa new DH key during each handshake but it is also recommended. 150109998SmarkmB<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever 15189837Skristemporary/ephemeral DH parameters are used. 15272613Skris 15372613Skris=item SSL_OP_EPHEMERAL_RSA 15472613Skris 155277195SdelphijThis option is no longer implemented and is treated as no op. 15672613Skris 157109998Smarkm=item SSL_OP_CIPHER_SERVER_PREFERENCE 158109998Smarkm 159109998SmarkmWhen choosing a cipher, use the server's preferences instead of the client 160109998Smarkmpreferences. When not set, the SSL server will always follow the clients 161109998Smarkmpreferences. When set, the SSLv3/TLSv1 server will choose following its 162109998Smarkmown preferences. Because of the different protocol, for SSLv2 the server 163160814Ssimonwill send its list of preferences to the client and the client chooses. 164109998Smarkm 16572613Skris=item SSL_OP_PKCS1_CHECK_1 16672613Skris 16772613Skris... 16872613Skris 16972613Skris=item SSL_OP_PKCS1_CHECK_2 17072613Skris 17172613Skris... 17272613Skris 17372613Skris=item SSL_OP_NETSCAPE_CA_DN_BUG 17472613Skris 17572613SkrisIf we accept a netscape connection, demand a client cert, have a 176120631Snectarnon-self-signed CA which does not have its CA in netscape, and the 17772613Skrisbrowser has a cert, it will crash/hang. Works for 3.x and 4.xbeta 17872613Skris 17972613Skris=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG 18072613Skris 18172613Skris... 18272613Skris 18372613Skris=item SSL_OP_NO_SSLv2 18472613Skris 18572613SkrisDo not use the SSLv2 protocol. 18672613Skris 18772613Skris=item SSL_OP_NO_SSLv3 18872613Skris 18972613SkrisDo not use the SSLv3 protocol. 19072613Skris 19172613Skris=item SSL_OP_NO_TLSv1 19272613Skris 19372613SkrisDo not use the TLSv1 protocol. 19472613Skris 195109998Smarkm=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION 196109998Smarkm 197109998SmarkmWhen performing renegotiation as a server, always start a new session 198109998Smarkm(i.e., session resumption requests are only accepted in the initial 199205128Ssimonhandshake). This option is not needed for clients. 200109998Smarkm 201194206Ssimon=item SSL_OP_NO_TICKET 202194206Ssimon 203194206SsimonNormally clients and servers will, where possible, transparently make use 204194206Ssimonof RFC4507bis tickets for stateless session resumption if extension support 205194206Ssimonis explicitly set when OpenSSL is compiled. 206194206Ssimon 207194206SsimonIf this option is set this functionality is disabled and tickets will 208194206Ssimonnot be used by clients or servers. 209194206Ssimon 210205128Ssimon=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION 211205128Ssimon 212205128SsimonAllow legacy insecure renegotiation between OpenSSL and unpatched clients or 213205128Ssimonservers. See the B<SECURE RENEGOTIATION> section for more details. 214205128Ssimon 215205128Ssimon=item SSL_OP_LEGACY_SERVER_CONNECT 216205128Ssimon 217205128SsimonAllow legacy insecure renegotiation between OpenSSL and unpatched servers 218205128SsimonB<only>: this option is currently set by default. See the 219205128SsimonB<SECURE RENEGOTIATION> section for more details. 220205128Ssimon 22172613Skris=back 22272613Skris 223205128Ssimon=head1 SECURE RENEGOTIATION 224205128Ssimon 225205128SsimonOpenSSL 0.9.8m and later always attempts to use secure renegotiation as 226205128Ssimondescribed in RFC5746. This counters the prefix attack described in 227205128SsimonCVE-2009-3555 and elsewhere. 228205128Ssimon 229205128SsimonThe deprecated and highly broken SSLv2 protocol does not support 230205128Ssimonrenegotiation at all: its use is B<strongly> discouraged. 231205128Ssimon 232205128SsimonThis attack has far reaching consequences which application writers should be 233205128Ssimonaware of. In the description below an implementation supporting secure 234205128Ssimonrenegotiation is referred to as I<patched>. A server not supporting secure 235205128Ssimonrenegotiation is referred to as I<unpatched>. 236205128Ssimon 237205128SsimonThe following sections describe the operations permitted by OpenSSL's secure 238205128Ssimonrenegotiation implementation. 239205128Ssimon 240205128Ssimon=head2 Patched client and server 241205128Ssimon 242205128SsimonConnections and renegotiation are always permitted by OpenSSL implementations. 243205128Ssimon 244205128Ssimon=head2 Unpatched client and patched OpenSSL server 245205128Ssimon 246279265SdelphijThe initial connection succeeds but client renegotiation is denied by the 247205128Ssimonserver with a B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal 248205128SsimonB<handshake_failure> alert in SSL v3.0. 249205128Ssimon 250205128SsimonIf the patched OpenSSL server attempts to renegotiate a fatal 251205128SsimonB<handshake_failure> alert is sent. This is because the server code may be 252205128Ssimonunaware of the unpatched nature of the client. 253205128Ssimon 254205128SsimonIf the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then 255205128Ssimonrenegotiation B<always> succeeds. 256205128Ssimon 257205128SsimonB<NB:> a bug in OpenSSL clients earlier than 0.9.8m (all of which are 258205128Ssimonunpatched) will result in the connection hanging if it receives a 259205128SsimonB<no_renegotiation> alert. OpenSSL versions 0.9.8m and later will regard 260205128Ssimona B<no_renegotiation> alert as fatal and respond with a fatal 261205128SsimonB<handshake_failure> alert. This is because the OpenSSL API currently has 262205128Ssimonno provision to indicate to an application that a renegotiation attempt 263205128Ssimonwas refused. 264205128Ssimon 265205128Ssimon=head2 Patched OpenSSL client and unpatched server. 266205128Ssimon 267205128SsimonIf the option B<SSL_OP_LEGACY_SERVER_CONNECT> or 268205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections 269205128Ssimonand renegotiation between patched OpenSSL clients and unpatched servers 270205128Ssimonsucceeds. If neither option is set then initial connections to unpatched 271205128Ssimonservers will fail. 272205128Ssimon 273205128SsimonThe option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even 274205128Ssimonthough it has security implications: otherwise it would be impossible to 275205128Ssimonconnect to unpatched servers (i.e. all of them initially) and this is clearly 276205128Ssimonnot acceptable. Renegotiation is permitted because this does not add any 277205128Ssimonadditional security issues: during an attack clients do not see any 278205128Ssimonrenegotiations anyway. 279205128Ssimon 280205128SsimonAs more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will 281205128SsimonB<not> be set by default in a future version of OpenSSL. 282205128Ssimon 283205128SsimonOpenSSL client applications wishing to ensure they can connect to unpatched 284205128Ssimonservers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT> 285205128Ssimon 286205128SsimonOpenSSL client applications that want to ensure they can B<not> connect to 287205128Ssimonunpatched servers (and thus avoid any security issues) should always B<clear> 288205128SsimonB<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or 289205128SsimonSSL_clear_options(). 290205128Ssimon 291205128SsimonThe difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and 292205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that 293205128SsimonB<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure 294205128Ssimonrenegotiation between OpenSSL clients and unpatched servers B<only>, while 295205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections 296205128Ssimonand renegotiation between OpenSSL and unpatched clients or servers. 297205128Ssimon 29872613Skris=head1 RETURN VALUES 29972613Skris 30072613SkrisSSL_CTX_set_options() and SSL_set_options() return the new options bitmask 30172613Skrisafter adding B<options>. 30272613Skris 303205128SsimonSSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask 304205128Ssimonafter clearing B<options>. 305205128Ssimon 30672613SkrisSSL_CTX_get_options() and SSL_get_options() return the current bitmask. 30772613Skris 308205128SsimonSSL_get_secure_renegotiation_support() returns 1 is the peer supports 309205128Ssimonsecure renegotiation and 0 if it does not. 310205128Ssimon 31172613Skris=head1 SEE ALSO 31272613Skris 31389837SkrisL<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, 31489837SkrisL<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, 31589837SkrisL<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 31689837SkrisL<dhparam(1)|dhparam(1)> 31772613Skris 31872613Skris=head1 HISTORY 31972613Skris 320109998SmarkmB<SSL_OP_CIPHER_SERVER_PREFERENCE> and 321109998SmarkmB<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> have been added in 322109998SmarkmOpenSSL 0.9.7. 32372613Skris 324109998SmarkmB<SSL_OP_TLS_ROLLBACK_BUG> has been added in OpenSSL 0.9.6 and was automatically 325109998Smarkmenabled with B<SSL_OP_ALL>. As of 0.9.7, it is no longer included in B<SSL_OP_ALL> 326109998Smarkmand must be explicitly set. 327109998Smarkm 328100936SnectarB<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e. 329100936SnectarVersions up to OpenSSL 0.9.6c do not include the countermeasure that 330100936Snectarcan be disabled with this option (in OpenSSL 0.9.6d, it was always 331100936Snectarenabled). 332100936Snectar 333205128SsimonSSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL 334205128Ssimon0.9.8m. 335205128Ssimon 336205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>, B<SSL_OP_LEGACY_SERVER_CONNECT> 337205128Ssimonand the function SSL_get_secure_renegotiation_support() were first added in 338205128SsimonOpenSSL 0.9.8m. 339205128Ssimon 34072613Skris=cut 341