SSL_CTX_set_options.pod revision 100936
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 8972613Skris... 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 10372613Skris=item SSL_OP_TLS_ROLLBACK_BUG 10472613Skris 10572613SkrisDisable version rollback attack detection. 10672613Skris 10772613SkrisDuring the client key exchange, the client must send the same information 10872613Skrisabout acceptable SSL/TLS protocol levels as during the first hello. Some 10972613Skrisclients violate this rule by adapting to the server's answer. (Example: 11072613Skristhe client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server 11172613Skrisonly understands up to SSLv3. In this case the client must still use the 11272613Skrissame SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect 11372613Skristo the server's answer and violate the version rollback protection.) 11472613Skris 115100936Snectar=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS 116100936Snectar 117100936SnectarDisables a countermeasure against a SSL 3.0/TLS 1.0 protocol 118100936Snectarvulnerability affecting CBC ciphers, which cannot be handled by some 119100936Snectarbroken SSL implementations. This option has no effect for connections 120100936Snectarusing other ciphers. 121100936Snectar 12272613Skris=item SSL_OP_ALL 12372613Skris 12472613SkrisAll of the above bug workarounds. 12572613Skris 12672613Skris=back 12772613Skris 128100936SnectarIt is usually safe to use B<SSL_OP_ALL> to enable the bug workaround 129100936Snectaroptions if compatibility with somewhat broken implementations is 130100936Snectardesired. 13172613Skris 13272613SkrisThe following B<modifying> options are available: 13372613Skris 13472613Skris=over 4 13572613Skris 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. 14589837SkrisSSL_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 16072613Skris=item SSL_OP_PKCS1_CHECK_1 16172613Skris 16272613Skris... 16372613Skris 16472613Skris=item SSL_OP_PKCS1_CHECK_2 16572613Skris 16672613Skris... 16772613Skris 16872613Skris=item SSL_OP_NETSCAPE_CA_DN_BUG 16972613Skris 17072613SkrisIf we accept a netscape connection, demand a client cert, have a 17172613Skrisnon-self-sighed CA which does not have it's CA in netscape, and the 17272613Skrisbrowser has a cert, it will crash/hang. Works for 3.x and 4.xbeta 17372613Skris 17472613Skris=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG 17572613Skris 17672613Skris... 17772613Skris 17872613Skris=item SSL_OP_NO_SSLv2 17972613Skris 18072613SkrisDo not use the SSLv2 protocol. 18172613Skris 18272613Skris=item SSL_OP_NO_SSLv3 18372613Skris 18472613SkrisDo not use the SSLv3 protocol. 18572613Skris 18672613Skris=item SSL_OP_NO_TLSv1 18772613Skris 18872613SkrisDo not use the TLSv1 protocol. 18972613Skris 19072613Skris=back 19172613Skris 19272613Skris=head1 RETURN VALUES 19372613Skris 19472613SkrisSSL_CTX_set_options() and SSL_set_options() return the new options bitmask 19572613Skrisafter adding B<options>. 19672613Skris 19772613SkrisSSL_CTX_get_options() and SSL_get_options() return the current bitmask. 19872613Skris 19972613Skris=head1 SEE ALSO 20072613Skris 20189837SkrisL<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, 20289837SkrisL<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, 20389837SkrisL<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 20489837SkrisL<dhparam(1)|dhparam(1)> 20572613Skris 20672613Skris=head1 HISTORY 20772613Skris 20872613SkrisSSL_OP_TLS_ROLLBACK_BUG has been added in OpenSSL 0.9.6. 20972613Skris 210100936SnectarB<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e. 211100936SnectarVersions up to OpenSSL 0.9.6c do not include the countermeasure that 212100936Snectarcan be disabled with this option (in OpenSSL 0.9.6d, it was always 213100936Snectarenabled). 214100936Snectar 21572613Skris=cut 216