SSL_CTX_set_options.pod revision 194206
172613Skris=pod 272613Skris 372613Skris=head1 NAME 472613Skris 572613SkrisSSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - manipulate SSL engine 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 1472613Skris long SSL_CTX_get_options(SSL_CTX *ctx); 1572613Skris long SSL_get_options(SSL *ssl); 1672613Skris 1772613Skris=head1 DESCRIPTION 1872613Skris 1972613SkrisSSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>. 2089837SkrisOptions already set before are not cleared! 2172613Skris 2272613SkrisSSL_set_options() adds the options set via bitmask in B<options> to B<ssl>. 2389837SkrisOptions already set before are not cleared! 2472613Skris 2572613SkrisSSL_CTX_get_options() returns the options set for B<ctx>. 2672613Skris 2772613SkrisSSL_get_options() returns the options set for B<ssl>. 2872613Skris 2972613Skris=head1 NOTES 3072613Skris 3172613SkrisThe behaviour of the SSL library can be changed by setting several options. 3272613SkrisThe options are coded as bitmasks and can be combined by a logical B<or> 3372613Skrisoperation (|). Options can only be added but can never be reset. 3472613Skris 3589837SkrisSSL_CTX_set_options() and SSL_set_options() affect the (external) 3689837Skrisprotocol behaviour of the SSL library. The (internal) behaviour of 3789837Skristhe API can be changed by using the similar 38100936SnectarL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> and SSL_set_mode() functions. 3989837Skris 4089837SkrisDuring a handshake, the option settings of the SSL object are used. When 4172613Skrisa new SSL object is created from a context using SSL_new(), the current 4272613Skrisoption setting is copied. Changes to B<ctx> do not affect already created 4372613SkrisSSL objects. SSL_clear() does not affect the settings. 4472613Skris 4572613SkrisThe following B<bug workaround> options are available: 4672613Skris 4772613Skris=over 4 4872613Skris 4972613Skris=item SSL_OP_MICROSOFT_SESS_ID_BUG 5072613Skris 5172613Skriswww.microsoft.com - when talking SSLv2, if session-id reuse is 5272613Skrisperformed, the session-id passed back in the server-finished message 5372613Skrisis different from the one decided upon. 5472613Skris 5572613Skris=item SSL_OP_NETSCAPE_CHALLENGE_BUG 5672613Skris 5772613SkrisNetscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte 5872613Skrischallenge but then appears to only use 16 bytes when generating the 5972613Skrisencryption keys. Using 16 bytes is ok but it should be ok to use 32. 6072613SkrisAccording to the SSLv3 spec, one should use 32 bytes for the challenge 6176866Skriswhen operating in SSLv2/v3 compatibility mode, but as mentioned above, 6272613Skristhis breaks this server so 16 bytes is the way to go. 6372613Skris 6472613Skris=item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG 6572613Skris 6672613Skrisssl3.netscape.com:443, first a connection is established with RC4-MD5. 6772613SkrisIf it is then resumed, we end up using DES-CBC3-SHA. It should be 6872613SkrisRC4-MD5 according to 7.6.1.3, 'cipher_suite'. 6972613Skris 7072613SkrisNetscape-Enterprise/2.01 (https://merchant.netscape.com) has this bug. 7172613SkrisIt only really shows up when connecting via SSLv2/v3 then reconnecting 7272613Skrisvia SSLv3. The cipher list changes.... 7372613Skris 7472613SkrisNEW INFORMATION. Try connecting with a cipher list of just 7572613SkrisDES-CBC-SHA:RC4-MD5. For some weird reason, each new connection uses 7672613SkrisRC4-MD5, but a re-connect tries to use DES-CBC-SHA. So netscape, when 7772613Skrisdoing a re-connect, always takes the first cipher in the cipher list. 7872613Skris 7972613Skris=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG 8072613Skris 8172613Skris... 8272613Skris 8372613Skris=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER 8472613Skris 8572613Skris... 8672613Skris 8772613Skris=item SSL_OP_MSIE_SSLV2_RSA_PADDING 8872613Skris 89160814SsimonAs of OpenSSL 0.9.7h and 0.9.8a, this option has no effect. 9072613Skris 9172613Skris=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG 9272613Skris 9372613Skris... 9472613Skris 9572613Skris=item SSL_OP_TLS_D5_BUG 9672613Skris 9772613Skris... 9872613Skris 9972613Skris=item SSL_OP_TLS_BLOCK_PADDING_BUG 10072613Skris 10172613Skris... 10272613Skris 103100936Snectar=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS 104100936Snectar 105100936SnectarDisables a countermeasure against a SSL 3.0/TLS 1.0 protocol 106100936Snectarvulnerability affecting CBC ciphers, which cannot be handled by some 107100936Snectarbroken SSL implementations. This option has no effect for connections 108100936Snectarusing other ciphers. 109100936Snectar 11072613Skris=item SSL_OP_ALL 11172613Skris 11272613SkrisAll of the above bug workarounds. 11372613Skris 11472613Skris=back 11572613Skris 116100936SnectarIt is usually safe to use B<SSL_OP_ALL> to enable the bug workaround 117100936Snectaroptions if compatibility with somewhat broken implementations is 118100936Snectardesired. 11972613Skris 12072613SkrisThe following B<modifying> options are available: 12172613Skris 12272613Skris=over 4 12372613Skris 124109998Smarkm=item SSL_OP_TLS_ROLLBACK_BUG 125109998Smarkm 126109998SmarkmDisable version rollback attack detection. 127109998Smarkm 128109998SmarkmDuring the client key exchange, the client must send the same information 129109998Smarkmabout acceptable SSL/TLS protocol levels as during the first hello. Some 130109998Smarkmclients violate this rule by adapting to the server's answer. (Example: 131109998Smarkmthe client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server 132109998Smarkmonly understands up to SSLv3. In this case the client must still use the 133109998Smarkmsame SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect 134109998Smarkmto the server's answer and violate the version rollback protection.) 135109998Smarkm 13672613Skris=item SSL_OP_SINGLE_DH_USE 13772613Skris 13889837SkrisAlways create a new key when using temporary/ephemeral DH parameters 13989837Skris(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>). 14089837SkrisThis option must be used to prevent small subgroup attacks, when 14189837Skristhe DH parameters were not generated using "strong" primes 14289837Skris(e.g. when using DSA-parameters, see L<dhparam(1)|dhparam(1)>). 14389837SkrisIf "strong" primes were used, it is not strictly necessary to generate 14489837Skrisa new DH key during each handshake but it is also recommended. 145109998SmarkmB<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever 14689837Skristemporary/ephemeral DH parameters are used. 14772613Skris 14872613Skris=item SSL_OP_EPHEMERAL_RSA 14972613Skris 15089837SkrisAlways use ephemeral (temporary) RSA key when doing RSA operations 15189837Skris(see L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>). 15289837SkrisAccording to the specifications this is only done, when a RSA key 15389837Skriscan only be used for signature operations (namely under export ciphers 15489837Skriswith restricted RSA keylength). By setting this option, ephemeral 15589837SkrisRSA keys are always used. This option breaks compatibility with the 15689837SkrisSSL/TLS specifications and may lead to interoperability problems with 15789837Skrisclients and should therefore never be used. Ciphers with EDH (ephemeral 15889837SkrisDiffie-Hellman) key exchange should be used instead. 15972613Skris 160109998Smarkm=item SSL_OP_CIPHER_SERVER_PREFERENCE 161109998Smarkm 162109998SmarkmWhen choosing a cipher, use the server's preferences instead of the client 163109998Smarkmpreferences. When not set, the SSL server will always follow the clients 164109998Smarkmpreferences. When set, the SSLv3/TLSv1 server will choose following its 165109998Smarkmown preferences. Because of the different protocol, for SSLv2 the server 166160814Ssimonwill send its list of preferences to the client and the client chooses. 167109998Smarkm 16872613Skris=item SSL_OP_PKCS1_CHECK_1 16972613Skris 17072613Skris... 17172613Skris 17272613Skris=item SSL_OP_PKCS1_CHECK_2 17372613Skris 17472613Skris... 17572613Skris 17672613Skris=item SSL_OP_NETSCAPE_CA_DN_BUG 17772613Skris 17872613SkrisIf we accept a netscape connection, demand a client cert, have a 179120631Snectarnon-self-signed CA which does not have its CA in netscape, and the 18072613Skrisbrowser has a cert, it will crash/hang. Works for 3.x and 4.xbeta 18172613Skris 18272613Skris=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG 18372613Skris 18472613Skris... 18572613Skris 18672613Skris=item SSL_OP_NO_SSLv2 18772613Skris 18872613SkrisDo not use the SSLv2 protocol. 18972613Skris 19072613Skris=item SSL_OP_NO_SSLv3 19172613Skris 19272613SkrisDo not use the SSLv3 protocol. 19372613Skris 19472613Skris=item SSL_OP_NO_TLSv1 19572613Skris 19672613SkrisDo not use the TLSv1 protocol. 19772613Skris 198109998Smarkm=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION 199109998Smarkm 200109998SmarkmWhen performing renegotiation as a server, always start a new session 201109998Smarkm(i.e., session resumption requests are only accepted in the initial 202109998Smarkmhandshake). This option is not needed for clients. 203109998Smarkm 204194206Ssimon=item SSL_OP_NO_TICKET 205194206Ssimon 206194206SsimonNormally clients and servers will, where possible, transparently make use 207194206Ssimonof RFC4507bis tickets for stateless session resumption if extension support 208194206Ssimonis explicitly set when OpenSSL is compiled. 209194206Ssimon 210194206SsimonIf this option is set this functionality is disabled and tickets will 211194206Ssimonnot be used by clients or servers. 212194206Ssimon 21372613Skris=back 21472613Skris 21572613Skris=head1 RETURN VALUES 21672613Skris 21772613SkrisSSL_CTX_set_options() and SSL_set_options() return the new options bitmask 21872613Skrisafter adding B<options>. 21972613Skris 22072613SkrisSSL_CTX_get_options() and SSL_get_options() return the current bitmask. 22172613Skris 22272613Skris=head1 SEE ALSO 22372613Skris 22489837SkrisL<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, 22589837SkrisL<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, 22689837SkrisL<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 22789837SkrisL<dhparam(1)|dhparam(1)> 22872613Skris 22972613Skris=head1 HISTORY 23072613Skris 231109998SmarkmB<SSL_OP_CIPHER_SERVER_PREFERENCE> and 232109998SmarkmB<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> have been added in 233109998SmarkmOpenSSL 0.9.7. 23472613Skris 235109998SmarkmB<SSL_OP_TLS_ROLLBACK_BUG> has been added in OpenSSL 0.9.6 and was automatically 236109998Smarkmenabled with B<SSL_OP_ALL>. As of 0.9.7, it is no longer included in B<SSL_OP_ALL> 237109998Smarkmand must be explicitly set. 238109998Smarkm 239100936SnectarB<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e. 240100936SnectarVersions up to OpenSSL 0.9.6c do not include the countermeasure that 241100936Snectarcan be disabled with this option (in OpenSSL 0.9.6d, it was always 242100936Snectarenabled). 243100936Snectar 24472613Skris=cut 245