SSL_CTX_set_options.pod revision 109998
1178825Sdfr=pod 2178825Sdfr 3178825Sdfr=head1 NAME 4178825Sdfr 5178825SdfrSSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - manipulate SSL engine options 6178825Sdfr 7178825Sdfr=head1 SYNOPSIS 8178825Sdfr 9178825Sdfr #include <openssl/ssl.h> 10178825Sdfr 11178825Sdfr long SSL_CTX_set_options(SSL_CTX *ctx, long options); 12178825Sdfr long SSL_set_options(SSL *ssl, long options); 13178825Sdfr 14178825Sdfr long SSL_CTX_get_options(SSL_CTX *ctx); 15178825Sdfr long SSL_get_options(SSL *ssl); 16178825Sdfr 17178825Sdfr=head1 DESCRIPTION 18178825Sdfr 19178825SdfrSSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>. 20178825SdfrOptions already set before are not cleared! 21178825Sdfr 22178825SdfrSSL_set_options() adds the options set via bitmask in B<options> to B<ssl>. 23178825SdfrOptions already set before are not cleared! 24178825Sdfr 25178825SdfrSSL_CTX_get_options() returns the options set for B<ctx>. 26178825Sdfr 27178825SdfrSSL_get_options() returns the options set for B<ssl>. 28178825Sdfr 29178825Sdfr=head1 NOTES 30178825Sdfr 31178825SdfrThe behaviour of the SSL library can be changed by setting several options. 32178825SdfrThe options are coded as bitmasks and can be combined by a logical B<or> 33178825Sdfroperation (|). Options can only be added but can never be reset. 34178825Sdfr 35178825SdfrSSL_CTX_set_options() and SSL_set_options() affect the (external) 36178825Sdfrprotocol behaviour of the SSL library. The (internal) behaviour of 37178825Sdfrthe API can be changed by using the similar 38178825SdfrL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> and SSL_set_mode() functions. 39178825Sdfr 40178825SdfrDuring a handshake, the option settings of the SSL object are used. When 41178825Sdfra new SSL object is created from a context using SSL_new(), the current 42178825Sdfroption setting is copied. Changes to B<ctx> do not affect already created 43178825SdfrSSL objects. SSL_clear() does not affect the settings. 44178825Sdfr 45178825SdfrThe following B<bug workaround> options are available: 46178825Sdfr 47178825Sdfr=over 4 48178825Sdfr 49178825Sdfr=item SSL_OP_MICROSOFT_SESS_ID_BUG 50178825Sdfr 51178825Sdfrwww.microsoft.com - when talking SSLv2, if session-id reuse is 52178825Sdfrperformed, the session-id passed back in the server-finished message 53178825Sdfris different from the one decided upon. 54178825Sdfr 55178825Sdfr=item SSL_OP_NETSCAPE_CHALLENGE_BUG 56178825Sdfr 57178825SdfrNetscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte 58178825Sdfrchallenge but then appears to only use 16 bytes when generating the 59178825Sdfrencryption keys. Using 16 bytes is ok but it should be ok to use 32. 60178825SdfrAccording to the SSLv3 spec, one should use 32 bytes for the challenge 61178825Sdfrwhen operating in SSLv2/v3 compatibility mode, but as mentioned above, 62178825Sdfrthis breaks this server so 16 bytes is the way to go. 63178825Sdfr 64178825Sdfr=item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG 65178825Sdfr 66178825Sdfrssl3.netscape.com:443, first a connection is established with RC4-MD5. 67178825SdfrIf it is then resumed, we end up using DES-CBC3-SHA. It should be 68178825SdfrRC4-MD5 according to 7.6.1.3, 'cipher_suite'. 69178825Sdfr 70178825SdfrNetscape-Enterprise/2.01 (https://merchant.netscape.com) has this bug. 71178825SdfrIt only really shows up when connecting via SSLv2/v3 then reconnecting 72178825Sdfrvia SSLv3. The cipher list changes.... 73178825Sdfr 74178825SdfrNEW INFORMATION. Try connecting with a cipher list of just 75178825SdfrDES-CBC-SHA:RC4-MD5. For some weird reason, each new connection uses 76178825SdfrRC4-MD5, but a re-connect tries to use DES-CBC-SHA. So netscape, when 77178825Sdfrdoing a re-connect, always takes the first cipher in the cipher list. 78178825Sdfr 79178825Sdfr=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG 80178825Sdfr 81178825Sdfr... 82178825Sdfr 83178825Sdfr=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER 84178825Sdfr 85178825Sdfr... 86178825Sdfr 87178825Sdfr=item SSL_OP_MSIE_SSLV2_RSA_PADDING 88178825Sdfr 89178825Sdfr... 90178825Sdfr 91178825Sdfr=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG 92178825Sdfr 93178825Sdfr... 94178825Sdfr 95178825Sdfr=item SSL_OP_TLS_D5_BUG 96178825Sdfr 97178825Sdfr... 98178825Sdfr 99178825Sdfr=item SSL_OP_TLS_BLOCK_PADDING_BUG 100178825Sdfr 101178825Sdfr... 102178825Sdfr 103178825Sdfr=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS 104178825Sdfr 105178825SdfrDisables a countermeasure against a SSL 3.0/TLS 1.0 protocol 106178825Sdfrvulnerability affecting CBC ciphers, which cannot be handled by some 107178825Sdfrbroken SSL implementations. This option has no effect for connections 108178825Sdfrusing other ciphers. 109178825Sdfr 110178825Sdfr=item SSL_OP_ALL 111178825Sdfr 112178825SdfrAll of the above bug workarounds. 113178825Sdfr 114178825Sdfr=back 115178825Sdfr 116178825SdfrIt is usually safe to use B<SSL_OP_ALL> to enable the bug workaround 117178825Sdfroptions if compatibility with somewhat broken implementations is 118178825Sdfrdesired. 119178825Sdfr 120178825SdfrThe following B<modifying> options are available: 121178825Sdfr 122178825Sdfr=over 4 123178825Sdfr 124178825Sdfr=item SSL_OP_TLS_ROLLBACK_BUG 125178825Sdfr 126178825SdfrDisable version rollback attack detection. 127178825Sdfr 128178825SdfrDuring the client key exchange, the client must send the same information 129178825Sdfrabout acceptable SSL/TLS protocol levels as during the first hello. Some 130178825Sdfrclients violate this rule by adapting to the server's answer. (Example: 131178825Sdfrthe client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server 132178825Sdfronly understands up to SSLv3. In this case the client must still use the 133178825Sdfrsame SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect 134178825Sdfrto the server's answer and violate the version rollback protection.) 135178825Sdfr 136178825Sdfr=item SSL_OP_SINGLE_DH_USE 137178825Sdfr 138178825SdfrAlways create a new key when using temporary/ephemeral DH parameters 139178825Sdfr(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>). 140178825SdfrThis option must be used to prevent small subgroup attacks, when 141178825Sdfrthe DH parameters were not generated using "strong" primes 142178825Sdfr(e.g. when using DSA-parameters, see L<dhparam(1)|dhparam(1)>). 143178825SdfrIf "strong" primes were used, it is not strictly necessary to generate 144178825Sdfra new DH key during each handshake but it is also recommended. 145178825SdfrB<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever 146178825Sdfrtemporary/ephemeral DH parameters are used. 147178825Sdfr 148178825Sdfr=item SSL_OP_EPHEMERAL_RSA 149178825Sdfr 150178825SdfrAlways use ephemeral (temporary) RSA key when doing RSA operations 151178825Sdfr(see L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>). 152178825SdfrAccording to the specifications this is only done, when a RSA key 153178825Sdfrcan only be used for signature operations (namely under export ciphers 154178825Sdfrwith restricted RSA keylength). By setting this option, ephemeral 155178825SdfrRSA keys are always used. This option breaks compatibility with the 156178825SdfrSSL/TLS specifications and may lead to interoperability problems with 157178825Sdfrclients and should therefore never be used. Ciphers with EDH (ephemeral 158178825SdfrDiffie-Hellman) key exchange should be used instead. 159178825Sdfr 160178825Sdfr=item SSL_OP_CIPHER_SERVER_PREFERENCE 161178825Sdfr 162178825SdfrWhen choosing a cipher, use the server's preferences instead of the client 163178825Sdfrpreferences. When not set, the SSL server will always follow the clients 164178825Sdfrpreferences. When set, the SSLv3/TLSv1 server will choose following its 165178825Sdfrown preferences. Because of the different protocol, for SSLv2 the server 166178825Sdfrwill send his list of preferences to the client and the client chooses. 167178825Sdfr 168178825Sdfr=item SSL_OP_PKCS1_CHECK_1 169178825Sdfr 170178825Sdfr... 171178825Sdfr 172178825Sdfr=item SSL_OP_PKCS1_CHECK_2 173178825Sdfr 174178825Sdfr... 175178825Sdfr 176178825Sdfr=item SSL_OP_NETSCAPE_CA_DN_BUG 177178825Sdfr 178178825SdfrIf we accept a netscape connection, demand a client cert, have a 179178825Sdfrnon-self-sighed CA which does not have it's CA in netscape, and the 180178825Sdfrbrowser has a cert, it will crash/hang. Works for 3.x and 4.xbeta 181178825Sdfr 182178825Sdfr=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG 183178825Sdfr 184178825Sdfr... 185178825Sdfr 186178825Sdfr=item SSL_OP_NO_SSLv2 187178825Sdfr 188178825SdfrDo not use the SSLv2 protocol. 189178825Sdfr 190178825Sdfr=item SSL_OP_NO_SSLv3 191178825Sdfr 192178825SdfrDo not use the SSLv3 protocol. 193178825Sdfr 194178825Sdfr=item SSL_OP_NO_TLSv1 195178825Sdfr 196178825SdfrDo not use the TLSv1 protocol. 197178825Sdfr 198178825Sdfr=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION 199178825Sdfr 200178825SdfrWhen performing renegotiation as a server, always start a new session 201178825Sdfr(i.e., session resumption requests are only accepted in the initial 202178825Sdfrhandshake). This option is not needed for clients. 203 204=back 205 206=head1 RETURN VALUES 207 208SSL_CTX_set_options() and SSL_set_options() return the new options bitmask 209after adding B<options>. 210 211SSL_CTX_get_options() and SSL_get_options() return the current bitmask. 212 213=head1 SEE ALSO 214 215L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, 216L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, 217L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 218L<dhparam(1)|dhparam(1)> 219 220=head1 HISTORY 221 222B<SSL_OP_CIPHER_SERVER_PREFERENCE> and 223B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> have been added in 224OpenSSL 0.9.7. 225 226B<SSL_OP_TLS_ROLLBACK_BUG> has been added in OpenSSL 0.9.6 and was automatically 227enabled with B<SSL_OP_ALL>. As of 0.9.7, it is no longer included in B<SSL_OP_ALL> 228and must be explicitly set. 229 230B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e. 231Versions up to OpenSSL 0.9.6c do not include the countermeasure that 232can be disabled with this option (in OpenSSL 0.9.6d, it was always 233enabled). 234 235=cut 236