SSL_CTX_set_options.pod revision 205128
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 8172613Skrisssl3.netscape.com:443, first a connection is established with RC4-MD5. 8272613SkrisIf it is then resumed, we end up using DES-CBC3-SHA. It should be 8372613SkrisRC4-MD5 according to 7.6.1.3, 'cipher_suite'. 8472613Skris 8572613SkrisNetscape-Enterprise/2.01 (https://merchant.netscape.com) has this bug. 8672613SkrisIt only really shows up when connecting via SSLv2/v3 then reconnecting 8772613Skrisvia SSLv3. The cipher list changes.... 8872613Skris 8972613SkrisNEW INFORMATION. Try connecting with a cipher list of just 9072613SkrisDES-CBC-SHA:RC4-MD5. For some weird reason, each new connection uses 9172613SkrisRC4-MD5, but a re-connect tries to use DES-CBC-SHA. So netscape, when 9272613Skrisdoing a re-connect, always takes the first cipher in the cipher list. 9372613Skris 9472613Skris=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG 9572613Skris 9672613Skris... 9772613Skris 9872613Skris=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER 9972613Skris 10072613Skris... 10172613Skris 10272613Skris=item SSL_OP_MSIE_SSLV2_RSA_PADDING 10372613Skris 104160814SsimonAs of OpenSSL 0.9.7h and 0.9.8a, this option has no effect. 10572613Skris 10672613Skris=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG 10772613Skris 10872613Skris... 10972613Skris 11072613Skris=item SSL_OP_TLS_D5_BUG 11172613Skris 11272613Skris... 11372613Skris 11472613Skris=item SSL_OP_TLS_BLOCK_PADDING_BUG 11572613Skris 11672613Skris... 11772613Skris 118100936Snectar=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS 119100936Snectar 120100936SnectarDisables a countermeasure against a SSL 3.0/TLS 1.0 protocol 121100936Snectarvulnerability affecting CBC ciphers, which cannot be handled by some 122100936Snectarbroken SSL implementations. This option has no effect for connections 123100936Snectarusing other ciphers. 124100936Snectar 12572613Skris=item SSL_OP_ALL 12672613Skris 12772613SkrisAll of the above bug workarounds. 12872613Skris 12972613Skris=back 13072613Skris 131100936SnectarIt is usually safe to use B<SSL_OP_ALL> to enable the bug workaround 132100936Snectaroptions if compatibility with somewhat broken implementations is 133100936Snectardesired. 13472613Skris 13572613SkrisThe following B<modifying> options are available: 13672613Skris 13772613Skris=over 4 13872613Skris 139109998Smarkm=item SSL_OP_TLS_ROLLBACK_BUG 140109998Smarkm 141109998SmarkmDisable version rollback attack detection. 142109998Smarkm 143109998SmarkmDuring the client key exchange, the client must send the same information 144109998Smarkmabout acceptable SSL/TLS protocol levels as during the first hello. Some 145109998Smarkmclients violate this rule by adapting to the server's answer. (Example: 146109998Smarkmthe client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server 147109998Smarkmonly understands up to SSLv3. In this case the client must still use the 148109998Smarkmsame SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect 149109998Smarkmto the server's answer and violate the version rollback protection.) 150109998Smarkm 15172613Skris=item SSL_OP_SINGLE_DH_USE 15272613Skris 15389837SkrisAlways create a new key when using temporary/ephemeral DH parameters 15489837Skris(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>). 15589837SkrisThis option must be used to prevent small subgroup attacks, when 15689837Skristhe DH parameters were not generated using "strong" primes 15789837Skris(e.g. when using DSA-parameters, see L<dhparam(1)|dhparam(1)>). 15889837SkrisIf "strong" primes were used, it is not strictly necessary to generate 15989837Skrisa new DH key during each handshake but it is also recommended. 160109998SmarkmB<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever 16189837Skristemporary/ephemeral DH parameters are used. 16272613Skris 16372613Skris=item SSL_OP_EPHEMERAL_RSA 16472613Skris 16589837SkrisAlways use ephemeral (temporary) RSA key when doing RSA operations 16689837Skris(see L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>). 16789837SkrisAccording to the specifications this is only done, when a RSA key 16889837Skriscan only be used for signature operations (namely under export ciphers 16989837Skriswith restricted RSA keylength). By setting this option, ephemeral 17089837SkrisRSA keys are always used. This option breaks compatibility with the 17189837SkrisSSL/TLS specifications and may lead to interoperability problems with 17289837Skrisclients and should therefore never be used. Ciphers with EDH (ephemeral 17389837SkrisDiffie-Hellman) key exchange should be used instead. 17472613Skris 175109998Smarkm=item SSL_OP_CIPHER_SERVER_PREFERENCE 176109998Smarkm 177109998SmarkmWhen choosing a cipher, use the server's preferences instead of the client 178109998Smarkmpreferences. When not set, the SSL server will always follow the clients 179109998Smarkmpreferences. When set, the SSLv3/TLSv1 server will choose following its 180109998Smarkmown preferences. Because of the different protocol, for SSLv2 the server 181160814Ssimonwill send its list of preferences to the client and the client chooses. 182109998Smarkm 18372613Skris=item SSL_OP_PKCS1_CHECK_1 18472613Skris 18572613Skris... 18672613Skris 18772613Skris=item SSL_OP_PKCS1_CHECK_2 18872613Skris 18972613Skris... 19072613Skris 19172613Skris=item SSL_OP_NETSCAPE_CA_DN_BUG 19272613Skris 19372613SkrisIf we accept a netscape connection, demand a client cert, have a 194120631Snectarnon-self-signed CA which does not have its CA in netscape, and the 19572613Skrisbrowser has a cert, it will crash/hang. Works for 3.x and 4.xbeta 19672613Skris 19772613Skris=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG 19872613Skris 19972613Skris... 20072613Skris 20172613Skris=item SSL_OP_NO_SSLv2 20272613Skris 20372613SkrisDo not use the SSLv2 protocol. 20472613Skris 20572613Skris=item SSL_OP_NO_SSLv3 20672613Skris 20772613SkrisDo not use the SSLv3 protocol. 20872613Skris 20972613Skris=item SSL_OP_NO_TLSv1 21072613Skris 21172613SkrisDo not use the TLSv1 protocol. 21272613Skris 213109998Smarkm=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION 214109998Smarkm 215109998SmarkmWhen performing renegotiation as a server, always start a new session 216109998Smarkm(i.e., session resumption requests are only accepted in the initial 217205128Ssimonhandshake). This option is not needed for clients. 218109998Smarkm 219194206Ssimon=item SSL_OP_NO_TICKET 220194206Ssimon 221194206SsimonNormally clients and servers will, where possible, transparently make use 222194206Ssimonof RFC4507bis tickets for stateless session resumption if extension support 223194206Ssimonis explicitly set when OpenSSL is compiled. 224194206Ssimon 225194206SsimonIf this option is set this functionality is disabled and tickets will 226194206Ssimonnot be used by clients or servers. 227194206Ssimon 228205128Ssimon=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION 229205128Ssimon 230205128SsimonAllow legacy insecure renegotiation between OpenSSL and unpatched clients or 231205128Ssimonservers. See the B<SECURE RENEGOTIATION> section for more details. 232205128Ssimon 233205128Ssimon=item SSL_OP_LEGACY_SERVER_CONNECT 234205128Ssimon 235205128SsimonAllow legacy insecure renegotiation between OpenSSL and unpatched servers 236205128SsimonB<only>: this option is currently set by default. See the 237205128SsimonB<SECURE RENEGOTIATION> section for more details. 238205128Ssimon 23972613Skris=back 24072613Skris 241205128Ssimon=head1 SECURE RENEGOTIATION 242205128Ssimon 243205128SsimonOpenSSL 0.9.8m and later always attempts to use secure renegotiation as 244205128Ssimondescribed in RFC5746. This counters the prefix attack described in 245205128SsimonCVE-2009-3555 and elsewhere. 246205128Ssimon 247205128SsimonThe deprecated and highly broken SSLv2 protocol does not support 248205128Ssimonrenegotiation at all: its use is B<strongly> discouraged. 249205128Ssimon 250205128SsimonThis attack has far reaching consequences which application writers should be 251205128Ssimonaware of. In the description below an implementation supporting secure 252205128Ssimonrenegotiation is referred to as I<patched>. A server not supporting secure 253205128Ssimonrenegotiation is referred to as I<unpatched>. 254205128Ssimon 255205128SsimonThe following sections describe the operations permitted by OpenSSL's secure 256205128Ssimonrenegotiation implementation. 257205128Ssimon 258205128Ssimon=head2 Patched client and server 259205128Ssimon 260205128SsimonConnections and renegotiation are always permitted by OpenSSL implementations. 261205128Ssimon 262205128Ssimon=head2 Unpatched client and patched OpenSSL server 263205128Ssimon 264205128SsimonThe initial connection suceeds but client renegotiation is denied by the 265205128Ssimonserver with a B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal 266205128SsimonB<handshake_failure> alert in SSL v3.0. 267205128Ssimon 268205128SsimonIf the patched OpenSSL server attempts to renegotiate a fatal 269205128SsimonB<handshake_failure> alert is sent. This is because the server code may be 270205128Ssimonunaware of the unpatched nature of the client. 271205128Ssimon 272205128SsimonIf the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then 273205128Ssimonrenegotiation B<always> succeeds. 274205128Ssimon 275205128SsimonB<NB:> a bug in OpenSSL clients earlier than 0.9.8m (all of which are 276205128Ssimonunpatched) will result in the connection hanging if it receives a 277205128SsimonB<no_renegotiation> alert. OpenSSL versions 0.9.8m and later will regard 278205128Ssimona B<no_renegotiation> alert as fatal and respond with a fatal 279205128SsimonB<handshake_failure> alert. This is because the OpenSSL API currently has 280205128Ssimonno provision to indicate to an application that a renegotiation attempt 281205128Ssimonwas refused. 282205128Ssimon 283205128Ssimon=head2 Patched OpenSSL client and unpatched server. 284205128Ssimon 285205128SsimonIf the option B<SSL_OP_LEGACY_SERVER_CONNECT> or 286205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections 287205128Ssimonand renegotiation between patched OpenSSL clients and unpatched servers 288205128Ssimonsucceeds. If neither option is set then initial connections to unpatched 289205128Ssimonservers will fail. 290205128Ssimon 291205128SsimonThe option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even 292205128Ssimonthough it has security implications: otherwise it would be impossible to 293205128Ssimonconnect to unpatched servers (i.e. all of them initially) and this is clearly 294205128Ssimonnot acceptable. Renegotiation is permitted because this does not add any 295205128Ssimonadditional security issues: during an attack clients do not see any 296205128Ssimonrenegotiations anyway. 297205128Ssimon 298205128SsimonAs more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will 299205128SsimonB<not> be set by default in a future version of OpenSSL. 300205128Ssimon 301205128SsimonOpenSSL client applications wishing to ensure they can connect to unpatched 302205128Ssimonservers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT> 303205128Ssimon 304205128SsimonOpenSSL client applications that want to ensure they can B<not> connect to 305205128Ssimonunpatched servers (and thus avoid any security issues) should always B<clear> 306205128SsimonB<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or 307205128SsimonSSL_clear_options(). 308205128Ssimon 309205128SsimonThe difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and 310205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that 311205128SsimonB<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure 312205128Ssimonrenegotiation between OpenSSL clients and unpatched servers B<only>, while 313205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections 314205128Ssimonand renegotiation between OpenSSL and unpatched clients or servers. 315205128Ssimon 31672613Skris=head1 RETURN VALUES 31772613Skris 31872613SkrisSSL_CTX_set_options() and SSL_set_options() return the new options bitmask 31972613Skrisafter adding B<options>. 32072613Skris 321205128SsimonSSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask 322205128Ssimonafter clearing B<options>. 323205128Ssimon 32472613SkrisSSL_CTX_get_options() and SSL_get_options() return the current bitmask. 32572613Skris 326205128SsimonSSL_get_secure_renegotiation_support() returns 1 is the peer supports 327205128Ssimonsecure renegotiation and 0 if it does not. 328205128Ssimon 32972613Skris=head1 SEE ALSO 33072613Skris 33189837SkrisL<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, 33289837SkrisL<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, 33389837SkrisL<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 33489837SkrisL<dhparam(1)|dhparam(1)> 33572613Skris 33672613Skris=head1 HISTORY 33772613Skris 338109998SmarkmB<SSL_OP_CIPHER_SERVER_PREFERENCE> and 339109998SmarkmB<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> have been added in 340109998SmarkmOpenSSL 0.9.7. 34172613Skris 342109998SmarkmB<SSL_OP_TLS_ROLLBACK_BUG> has been added in OpenSSL 0.9.6 and was automatically 343109998Smarkmenabled with B<SSL_OP_ALL>. As of 0.9.7, it is no longer included in B<SSL_OP_ALL> 344109998Smarkmand must be explicitly set. 345109998Smarkm 346100936SnectarB<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e. 347100936SnectarVersions up to OpenSSL 0.9.6c do not include the countermeasure that 348100936Snectarcan be disabled with this option (in OpenSSL 0.9.6d, it was always 349100936Snectarenabled). 350100936Snectar 351205128SsimonSSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL 352205128Ssimon0.9.8m. 353205128Ssimon 354205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>, B<SSL_OP_LEGACY_SERVER_CONNECT> 355205128Ssimonand the function SSL_get_secure_renegotiation_support() were first added in 356205128SsimonOpenSSL 0.9.8m. 357205128Ssimon 35872613Skris=cut 359