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. 192296279SjkimAs of OpenSSL 1.0.2g the B<SSL_OP_NO_SSLv2> option is set by default. 19372613Skris 19472613Skris=item SSL_OP_NO_SSLv3 19572613Skris 19672613SkrisDo not use the SSLv3 protocol. 197296279SjkimIt is recommended that applications should set this option. 19872613Skris 19972613Skris=item SSL_OP_NO_TLSv1 20072613Skris 20172613SkrisDo not use the TLSv1 protocol. 20272613Skris 203296279Sjkim=item SSL_OP_NO_TLSv1_1 204296279Sjkim 205296279SjkimDo not use the TLSv1.1 protocol. 206296279Sjkim 207296279Sjkim=item SSL_OP_NO_TLSv1_2 208296279Sjkim 209296279SjkimDo not use the TLSv1.2 protocol. 210296279Sjkim 211109998Smarkm=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION 212109998Smarkm 213109998SmarkmWhen performing renegotiation as a server, always start a new session 214109998Smarkm(i.e., session resumption requests are only accepted in the initial 215205128Ssimonhandshake). This option is not needed for clients. 216109998Smarkm 217194206Ssimon=item SSL_OP_NO_TICKET 218194206Ssimon 219194206SsimonNormally clients and servers will, where possible, transparently make use 220238405Sjkimof RFC4507bis tickets for stateless session resumption. 221194206Ssimon 222194206SsimonIf this option is set this functionality is disabled and tickets will 223194206Ssimonnot be used by clients or servers. 224194206Ssimon 225205128Ssimon=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION 226205128Ssimon 227205128SsimonAllow legacy insecure renegotiation between OpenSSL and unpatched clients or 228205128Ssimonservers. See the B<SECURE RENEGOTIATION> section for more details. 229205128Ssimon 230205128Ssimon=item SSL_OP_LEGACY_SERVER_CONNECT 231205128Ssimon 232205128SsimonAllow legacy insecure renegotiation between OpenSSL and unpatched servers 233205128SsimonB<only>: this option is currently set by default. See the 234205128SsimonB<SECURE RENEGOTIATION> section for more details. 235205128Ssimon 23672613Skris=back 23772613Skris 238205128Ssimon=head1 SECURE RENEGOTIATION 239205128Ssimon 240205128SsimonOpenSSL 0.9.8m and later always attempts to use secure renegotiation as 241205128Ssimondescribed in RFC5746. This counters the prefix attack described in 242205128SsimonCVE-2009-3555 and elsewhere. 243205128Ssimon 244205128SsimonThe deprecated and highly broken SSLv2 protocol does not support 245205128Ssimonrenegotiation at all: its use is B<strongly> discouraged. 246205128Ssimon 247205128SsimonThis attack has far reaching consequences which application writers should be 248205128Ssimonaware of. In the description below an implementation supporting secure 249205128Ssimonrenegotiation is referred to as I<patched>. A server not supporting secure 250205128Ssimonrenegotiation is referred to as I<unpatched>. 251205128Ssimon 252205128SsimonThe following sections describe the operations permitted by OpenSSL's secure 253205128Ssimonrenegotiation implementation. 254205128Ssimon 255205128Ssimon=head2 Patched client and server 256205128Ssimon 257205128SsimonConnections and renegotiation are always permitted by OpenSSL implementations. 258205128Ssimon 259205128Ssimon=head2 Unpatched client and patched OpenSSL server 260205128Ssimon 261269682SjkimThe initial connection succeeds but client renegotiation is denied by the 262205128Ssimonserver with a B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal 263205128SsimonB<handshake_failure> alert in SSL v3.0. 264205128Ssimon 265205128SsimonIf the patched OpenSSL server attempts to renegotiate a fatal 266205128SsimonB<handshake_failure> alert is sent. This is because the server code may be 267205128Ssimonunaware of the unpatched nature of the client. 268205128Ssimon 269205128SsimonIf the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then 270205128Ssimonrenegotiation B<always> succeeds. 271205128Ssimon 272205128SsimonB<NB:> a bug in OpenSSL clients earlier than 0.9.8m (all of which are 273205128Ssimonunpatched) will result in the connection hanging if it receives a 274205128SsimonB<no_renegotiation> alert. OpenSSL versions 0.9.8m and later will regard 275205128Ssimona B<no_renegotiation> alert as fatal and respond with a fatal 276205128SsimonB<handshake_failure> alert. This is because the OpenSSL API currently has 277205128Ssimonno provision to indicate to an application that a renegotiation attempt 278205128Ssimonwas refused. 279205128Ssimon 280205128Ssimon=head2 Patched OpenSSL client and unpatched server. 281205128Ssimon 282205128SsimonIf the option B<SSL_OP_LEGACY_SERVER_CONNECT> or 283205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections 284205128Ssimonand renegotiation between patched OpenSSL clients and unpatched servers 285205128Ssimonsucceeds. If neither option is set then initial connections to unpatched 286205128Ssimonservers will fail. 287205128Ssimon 288205128SsimonThe option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even 289205128Ssimonthough it has security implications: otherwise it would be impossible to 290205128Ssimonconnect to unpatched servers (i.e. all of them initially) and this is clearly 291205128Ssimonnot acceptable. Renegotiation is permitted because this does not add any 292205128Ssimonadditional security issues: during an attack clients do not see any 293205128Ssimonrenegotiations anyway. 294205128Ssimon 295205128SsimonAs more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will 296205128SsimonB<not> be set by default in a future version of OpenSSL. 297205128Ssimon 298205128SsimonOpenSSL client applications wishing to ensure they can connect to unpatched 299205128Ssimonservers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT> 300205128Ssimon 301205128SsimonOpenSSL client applications that want to ensure they can B<not> connect to 302205128Ssimonunpatched servers (and thus avoid any security issues) should always B<clear> 303205128SsimonB<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or 304205128SsimonSSL_clear_options(). 305205128Ssimon 306205128SsimonThe difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and 307205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that 308205128SsimonB<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure 309205128Ssimonrenegotiation between OpenSSL clients and unpatched servers B<only>, while 310205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections 311205128Ssimonand renegotiation between OpenSSL and unpatched clients or servers. 312205128Ssimon 31372613Skris=head1 RETURN VALUES 31472613Skris 31572613SkrisSSL_CTX_set_options() and SSL_set_options() return the new options bitmask 31672613Skrisafter adding B<options>. 31772613Skris 318205128SsimonSSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask 319205128Ssimonafter clearing B<options>. 320205128Ssimon 32172613SkrisSSL_CTX_get_options() and SSL_get_options() return the current bitmask. 32272613Skris 323205128SsimonSSL_get_secure_renegotiation_support() returns 1 is the peer supports 324205128Ssimonsecure renegotiation and 0 if it does not. 325205128Ssimon 32672613Skris=head1 SEE ALSO 32772613Skris 32889837SkrisL<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, 32989837SkrisL<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, 33089837SkrisL<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 33189837SkrisL<dhparam(1)|dhparam(1)> 33272613Skris 33372613Skris=head1 HISTORY 33472613Skris 335109998SmarkmB<SSL_OP_CIPHER_SERVER_PREFERENCE> and 336109998SmarkmB<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> have been added in 337109998SmarkmOpenSSL 0.9.7. 33872613Skris 339109998SmarkmB<SSL_OP_TLS_ROLLBACK_BUG> has been added in OpenSSL 0.9.6 and was automatically 340109998Smarkmenabled with B<SSL_OP_ALL>. As of 0.9.7, it is no longer included in B<SSL_OP_ALL> 341109998Smarkmand must be explicitly set. 342109998Smarkm 343100936SnectarB<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e. 344100936SnectarVersions up to OpenSSL 0.9.6c do not include the countermeasure that 345100936Snectarcan be disabled with this option (in OpenSSL 0.9.6d, it was always 346100936Snectarenabled). 347100936Snectar 348205128SsimonSSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL 349205128Ssimon0.9.8m. 350205128Ssimon 351205128SsimonB<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>, B<SSL_OP_LEGACY_SERVER_CONNECT> 352205128Ssimonand the function SSL_get_secure_renegotiation_support() were first added in 353205128SsimonOpenSSL 0.9.8m. 354205128Ssimon 35572613Skris=cut 356