SSL_CTX_set_options.pod revision 276861
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 91261037Sjkim=item SSL_OP_SAFARI_ECDHE_ECDSA_BUG 9272613Skris 93261037SjkimDon't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X. 94261037SjkimOS 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 115267256Sjkim=item SSL_OP_TLSEXT_PADDING 116267256Sjkim 117267256SjkimAdds a padding extension to ensure the ClientHello size is never between 118267256Sjkim256 and 511 bytes in length. This is needed as a workaround for some 119267256Sjkimimplementations. 120267256Sjkim 12172613Skris=item SSL_OP_ALL 12272613Skris 12372613SkrisAll of the above bug workarounds. 12472613Skris 12572613Skris=back 12672613Skris 127100936SnectarIt is usually safe to use B<SSL_OP_ALL> to enable the bug workaround 128100936Snectaroptions if compatibility with somewhat broken implementations is 129100936Snectardesired. 13072613Skris 13172613SkrisThe following B<modifying> options are available: 13272613Skris 13372613Skris=over 4 13472613Skris 135109998Smarkm=item SSL_OP_TLS_ROLLBACK_BUG 136109998Smarkm 137109998SmarkmDisable version rollback attack detection. 138109998Smarkm 139109998SmarkmDuring the client key exchange, the client must send the same information 140109998Smarkmabout acceptable SSL/TLS protocol levels as during the first hello. Some 141109998Smarkmclients violate this rule by adapting to the server's answer. (Example: 142109998Smarkmthe client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server 143109998Smarkmonly understands up to SSLv3. In this case the client must still use the 144109998Smarkmsame SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect 145109998Smarkmto the server's answer and violate the version rollback protection.) 146109998Smarkm 14772613Skris=item SSL_OP_SINGLE_DH_USE 14872613Skris 14989837SkrisAlways create a new key when using temporary/ephemeral DH parameters 15089837Skris(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>). 15189837SkrisThis option must be used to prevent small subgroup attacks, when 15289837Skristhe DH parameters were not generated using "strong" primes 15389837Skris(e.g. when using DSA-parameters, see L<dhparam(1)|dhparam(1)>). 15489837SkrisIf "strong" primes were used, it is not strictly necessary to generate 15589837Skrisa new DH key during each handshake but it is also recommended. 156109998SmarkmB<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever 15789837Skristemporary/ephemeral DH parameters are used. 15872613Skris 15972613Skris=item SSL_OP_EPHEMERAL_RSA 16072613Skris 161276861SjkimThis option is no longer implemented and is treated as no op. 16272613Skris 163109998Smarkm=item SSL_OP_CIPHER_SERVER_PREFERENCE 164109998Smarkm 165109998SmarkmWhen choosing a cipher, use the server's preferences instead of the client 166109998Smarkmpreferences. When not set, the SSL server will always follow the clients 167109998Smarkmpreferences. When set, the SSLv3/TLSv1 server will choose following its 168109998Smarkmown preferences. Because of the different protocol, for SSLv2 the server 169160814Ssimonwill send its list of preferences to the client and the client chooses. 170109998Smarkm 17172613Skris=item SSL_OP_PKCS1_CHECK_1 17272613Skris 17372613Skris... 17472613Skris 17572613Skris=item SSL_OP_PKCS1_CHECK_2 17672613Skris 17772613Skris... 17872613Skris 17972613Skris=item SSL_OP_NETSCAPE_CA_DN_BUG 18072613Skris 18172613SkrisIf we accept a netscape connection, demand a client cert, have a 182120631Snectarnon-self-signed CA which does not have its CA in netscape, and the 18372613Skrisbrowser has a cert, it will crash/hang. Works for 3.x and 4.xbeta 18472613Skris 18572613Skris=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG 18672613Skris 18772613Skris... 18872613Skris 18972613Skris=item SSL_OP_NO_SSLv2 19072613Skris 19172613SkrisDo not use the SSLv2 protocol. 19272613Skris 19372613Skris=item SSL_OP_NO_SSLv3 19472613Skris 19572613SkrisDo not use the SSLv3 protocol. 19672613Skris 19772613Skris=item SSL_OP_NO_TLSv1 19872613Skris 19972613SkrisDo not use the TLSv1 protocol. 20072613Skris 201109998Smarkm=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION 202109998Smarkm 203109998SmarkmWhen performing renegotiation as a server, always start a new session 204109998Smarkm(i.e., session resumption requests are only accepted in the initial 205205128Ssimonhandshake). This option is not needed for clients. 206109998Smarkm 207194206Ssimon=item SSL_OP_NO_TICKET 208194206Ssimon 209194206SsimonNormally clients and servers will, where possible, transparently make use 210238405Sjkimof RFC4507bis tickets for stateless session resumption. 211194206Ssimon 212194206SsimonIf this option is set this functionality is disabled and tickets will 213194206Ssimonnot be used by clients or servers. 214194206Ssimon 215205128Ssimon=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION 216205128Ssimon 217205128SsimonAllow legacy insecure renegotiation between OpenSSL and unpatched clients or 218205128Ssimonservers. See the B<SECURE RENEGOTIATION> section for more details. 219205128Ssimon 220205128Ssimon=item SSL_OP_LEGACY_SERVER_CONNECT 221205128Ssimon 222205128SsimonAllow legacy insecure renegotiation between OpenSSL and unpatched servers 223205128SsimonB<only>: this option is currently set by default. See the 224205128SsimonB<SECURE RENEGOTIATION> section for more details. 225205128Ssimon 22672613Skris=back 22772613Skris 228205128Ssimon=head1 SECURE RENEGOTIATION 229205128Ssimon 230205128SsimonOpenSSL 0.9.8m and later always attempts to use secure renegotiation as 231205128Ssimondescribed in RFC5746. This counters the prefix attack described in 232205128SsimonCVE-2009-3555 and elsewhere. 233205128Ssimon 234205128SsimonThe deprecated and highly broken SSLv2 protocol does not support 235205128Ssimonrenegotiation at all: its use is B<strongly> discouraged. 236205128Ssimon 237205128SsimonThis attack has far reaching consequences which application writers should be 238205128Ssimonaware of. In the description below an implementation supporting secure 239205128Ssimonrenegotiation is referred to as I<patched>. A server not supporting secure 240205128Ssimonrenegotiation is referred to as I<unpatched>. 241205128Ssimon 242205128SsimonThe following sections describe the operations permitted by OpenSSL's secure 243205128Ssimonrenegotiation implementation. 244205128Ssimon 245205128Ssimon=head2 Patched client and server 246205128Ssimon 247205128SsimonConnections and renegotiation are always permitted by OpenSSL implementations. 248205128Ssimon 249205128Ssimon=head2 Unpatched client and patched OpenSSL server 250205128Ssimon 251269682SjkimThe initial connection succeeds but client renegotiation is denied by the 252205128Ssimonserver with a B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal 253205128SsimonB<handshake_failure> alert in SSL v3.0. 254205128Ssimon 255205128SsimonIf the patched OpenSSL server attempts to renegotiate a fatal 256205128SsimonB<handshake_failure> alert is sent. This is because the server code may be 257205128Ssimonunaware of the unpatched nature of the client. 258205128Ssimon 259205128SsimonIf the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then 260205128Ssimonrenegotiation B<always> succeeds. 261205128Ssimon 262205128SsimonB<NB:> a bug in OpenSSL clients earlier than 0.9.8m (all of which are 263205128Ssimonunpatched) will result in the connection hanging if it receives a 264205128SsimonB<no_renegotiation> alert. OpenSSL versions 0.9.8m and later will regard 265205128Ssimona B<no_renegotiation> alert as fatal and respond with a fatal 266205128SsimonB<handshake_failure> alert. This is because the OpenSSL API currently has 267205128Ssimonno provision to indicate to an application that a renegotiation attempt 268205128Ssimonwas refused. 269205128Ssimon 270205128Ssimon=head2 Patched OpenSSL client and unpatched server. 271205128Ssimon 272205128SsimonIf the option B<SSL_OP_LEGACY_SERVER_CONNECT> or 273205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections 274205128Ssimonand renegotiation between patched OpenSSL clients and unpatched servers 275205128Ssimonsucceeds. If neither option is set then initial connections to unpatched 276205128Ssimonservers will fail. 277205128Ssimon 278205128SsimonThe option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even 279205128Ssimonthough it has security implications: otherwise it would be impossible to 280205128Ssimonconnect to unpatched servers (i.e. all of them initially) and this is clearly 281205128Ssimonnot acceptable. Renegotiation is permitted because this does not add any 282205128Ssimonadditional security issues: during an attack clients do not see any 283205128Ssimonrenegotiations anyway. 284205128Ssimon 285205128SsimonAs more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will 286205128SsimonB<not> be set by default in a future version of OpenSSL. 287205128Ssimon 288205128SsimonOpenSSL client applications wishing to ensure they can connect to unpatched 289205128Ssimonservers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT> 290205128Ssimon 291205128SsimonOpenSSL client applications that want to ensure they can B<not> connect to 292205128Ssimonunpatched servers (and thus avoid any security issues) should always B<clear> 293205128SsimonB<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or 294205128SsimonSSL_clear_options(). 295205128Ssimon 296205128SsimonThe difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and 297205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that 298205128SsimonB<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure 299205128Ssimonrenegotiation between OpenSSL clients and unpatched servers B<only>, while 300205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections 301205128Ssimonand renegotiation between OpenSSL and unpatched clients or servers. 302205128Ssimon 30372613Skris=head1 RETURN VALUES 30472613Skris 30572613SkrisSSL_CTX_set_options() and SSL_set_options() return the new options bitmask 30672613Skrisafter adding B<options>. 30772613Skris 308205128SsimonSSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask 309205128Ssimonafter clearing B<options>. 310205128Ssimon 31172613SkrisSSL_CTX_get_options() and SSL_get_options() return the current bitmask. 31272613Skris 313205128SsimonSSL_get_secure_renegotiation_support() returns 1 is the peer supports 314205128Ssimonsecure renegotiation and 0 if it does not. 315205128Ssimon 31672613Skris=head1 SEE ALSO 31772613Skris 31889837SkrisL<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, 31989837SkrisL<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, 32089837SkrisL<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 32189837SkrisL<dhparam(1)|dhparam(1)> 32272613Skris 32372613Skris=head1 HISTORY 32472613Skris 325109998SmarkmB<SSL_OP_CIPHER_SERVER_PREFERENCE> and 326109998SmarkmB<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> have been added in 327109998SmarkmOpenSSL 0.9.7. 32872613Skris 329109998SmarkmB<SSL_OP_TLS_ROLLBACK_BUG> has been added in OpenSSL 0.9.6 and was automatically 330109998Smarkmenabled with B<SSL_OP_ALL>. As of 0.9.7, it is no longer included in B<SSL_OP_ALL> 331109998Smarkmand must be explicitly set. 332109998Smarkm 333100936SnectarB<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e. 334100936SnectarVersions up to OpenSSL 0.9.6c do not include the countermeasure that 335100936Snectarcan be disabled with this option (in OpenSSL 0.9.6d, it was always 336100936Snectarenabled). 337100936Snectar 338205128SsimonSSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL 339205128Ssimon0.9.8m. 340205128Ssimon 341205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>, B<SSL_OP_LEGACY_SERVER_CONNECT> 342205128Ssimonand the function SSL_get_secure_renegotiation_support() were first added in 343205128SsimonOpenSSL 0.9.8m. 344205128Ssimon 34572613Skris=cut 346