1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - manipulate SSL engine options 6*2175Sjp161948 7*2175Sjp161948=head1 SYNOPSIS 8*2175Sjp161948 9*2175Sjp161948 #include <openssl/ssl.h> 10*2175Sjp161948 11*2175Sjp161948 long SSL_CTX_set_options(SSL_CTX *ctx, long options); 12*2175Sjp161948 long SSL_set_options(SSL *ssl, long options); 13*2175Sjp161948 14*2175Sjp161948 long SSL_CTX_get_options(SSL_CTX *ctx); 15*2175Sjp161948 long SSL_get_options(SSL *ssl); 16*2175Sjp161948 17*2175Sjp161948=head1 DESCRIPTION 18*2175Sjp161948 19*2175Sjp161948SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>. 20*2175Sjp161948Options already set before are not cleared! 21*2175Sjp161948 22*2175Sjp161948SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>. 23*2175Sjp161948Options already set before are not cleared! 24*2175Sjp161948 25*2175Sjp161948SSL_CTX_get_options() returns the options set for B<ctx>. 26*2175Sjp161948 27*2175Sjp161948SSL_get_options() returns the options set for B<ssl>. 28*2175Sjp161948 29*2175Sjp161948=head1 NOTES 30*2175Sjp161948 31*2175Sjp161948The behaviour of the SSL library can be changed by setting several options. 32*2175Sjp161948The options are coded as bitmasks and can be combined by a logical B<or> 33*2175Sjp161948operation (|). Options can only be added but can never be reset. 34*2175Sjp161948 35*2175Sjp161948SSL_CTX_set_options() and SSL_set_options() affect the (external) 36*2175Sjp161948protocol behaviour of the SSL library. The (internal) behaviour of 37*2175Sjp161948the API can be changed by using the similar 38*2175Sjp161948L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> and SSL_set_mode() functions. 39*2175Sjp161948 40*2175Sjp161948During a handshake, the option settings of the SSL object are used. When 41*2175Sjp161948a new SSL object is created from a context using SSL_new(), the current 42*2175Sjp161948option setting is copied. Changes to B<ctx> do not affect already created 43*2175Sjp161948SSL objects. SSL_clear() does not affect the settings. 44*2175Sjp161948 45*2175Sjp161948The following B<bug workaround> options are available: 46*2175Sjp161948 47*2175Sjp161948=over 4 48*2175Sjp161948 49*2175Sjp161948=item SSL_OP_MICROSOFT_SESS_ID_BUG 50*2175Sjp161948 51*2175Sjp161948www.microsoft.com - when talking SSLv2, if session-id reuse is 52*2175Sjp161948performed, the session-id passed back in the server-finished message 53*2175Sjp161948is different from the one decided upon. 54*2175Sjp161948 55*2175Sjp161948=item SSL_OP_NETSCAPE_CHALLENGE_BUG 56*2175Sjp161948 57*2175Sjp161948Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte 58*2175Sjp161948challenge but then appears to only use 16 bytes when generating the 59*2175Sjp161948encryption keys. Using 16 bytes is ok but it should be ok to use 32. 60*2175Sjp161948According to the SSLv3 spec, one should use 32 bytes for the challenge 61*2175Sjp161948when operating in SSLv2/v3 compatibility mode, but as mentioned above, 62*2175Sjp161948this breaks this server so 16 bytes is the way to go. 63*2175Sjp161948 64*2175Sjp161948=item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG 65*2175Sjp161948 66*2175Sjp161948ssl3.netscape.com:443, first a connection is established with RC4-MD5. 67*2175Sjp161948If it is then resumed, we end up using DES-CBC3-SHA. It should be 68*2175Sjp161948RC4-MD5 according to 7.6.1.3, 'cipher_suite'. 69*2175Sjp161948 70*2175Sjp161948Netscape-Enterprise/2.01 (https://merchant.netscape.com) has this bug. 71*2175Sjp161948It only really shows up when connecting via SSLv2/v3 then reconnecting 72*2175Sjp161948via SSLv3. The cipher list changes.... 73*2175Sjp161948 74*2175Sjp161948NEW INFORMATION. Try connecting with a cipher list of just 75*2175Sjp161948DES-CBC-SHA:RC4-MD5. For some weird reason, each new connection uses 76*2175Sjp161948RC4-MD5, but a re-connect tries to use DES-CBC-SHA. So netscape, when 77*2175Sjp161948doing a re-connect, always takes the first cipher in the cipher list. 78*2175Sjp161948 79*2175Sjp161948=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG 80*2175Sjp161948 81*2175Sjp161948... 82*2175Sjp161948 83*2175Sjp161948=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER 84*2175Sjp161948 85*2175Sjp161948... 86*2175Sjp161948 87*2175Sjp161948=item SSL_OP_MSIE_SSLV2_RSA_PADDING 88*2175Sjp161948 89*2175Sjp161948As of OpenSSL 0.9.7h and 0.9.8a, this option has no effect. 90*2175Sjp161948 91*2175Sjp161948=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG 92*2175Sjp161948 93*2175Sjp161948... 94*2175Sjp161948 95*2175Sjp161948=item SSL_OP_TLS_D5_BUG 96*2175Sjp161948 97*2175Sjp161948... 98*2175Sjp161948 99*2175Sjp161948=item SSL_OP_TLS_BLOCK_PADDING_BUG 100*2175Sjp161948 101*2175Sjp161948... 102*2175Sjp161948 103*2175Sjp161948=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS 104*2175Sjp161948 105*2175Sjp161948Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol 106*2175Sjp161948vulnerability affecting CBC ciphers, which cannot be handled by some 107*2175Sjp161948broken SSL implementations. This option has no effect for connections 108*2175Sjp161948using other ciphers. 109*2175Sjp161948 110*2175Sjp161948=item SSL_OP_ALL 111*2175Sjp161948 112*2175Sjp161948All of the above bug workarounds. 113*2175Sjp161948 114*2175Sjp161948=back 115*2175Sjp161948 116*2175Sjp161948It is usually safe to use B<SSL_OP_ALL> to enable the bug workaround 117*2175Sjp161948options if compatibility with somewhat broken implementations is 118*2175Sjp161948desired. 119*2175Sjp161948 120*2175Sjp161948The following B<modifying> options are available: 121*2175Sjp161948 122*2175Sjp161948=over 4 123*2175Sjp161948 124*2175Sjp161948=item SSL_OP_TLS_ROLLBACK_BUG 125*2175Sjp161948 126*2175Sjp161948Disable version rollback attack detection. 127*2175Sjp161948 128*2175Sjp161948During the client key exchange, the client must send the same information 129*2175Sjp161948about acceptable SSL/TLS protocol levels as during the first hello. Some 130*2175Sjp161948clients violate this rule by adapting to the server's answer. (Example: 131*2175Sjp161948the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server 132*2175Sjp161948only understands up to SSLv3. In this case the client must still use the 133*2175Sjp161948same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect 134*2175Sjp161948to the server's answer and violate the version rollback protection.) 135*2175Sjp161948 136*2175Sjp161948=item SSL_OP_SINGLE_DH_USE 137*2175Sjp161948 138*2175Sjp161948Always create a new key when using temporary/ephemeral DH parameters 139*2175Sjp161948(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>). 140*2175Sjp161948This option must be used to prevent small subgroup attacks, when 141*2175Sjp161948the DH parameters were not generated using "strong" primes 142*2175Sjp161948(e.g. when using DSA-parameters, see L<dhparam(1)|dhparam(1)>). 143*2175Sjp161948If "strong" primes were used, it is not strictly necessary to generate 144*2175Sjp161948a new DH key during each handshake but it is also recommended. 145*2175Sjp161948B<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever 146*2175Sjp161948temporary/ephemeral DH parameters are used. 147*2175Sjp161948 148*2175Sjp161948=item SSL_OP_EPHEMERAL_RSA 149*2175Sjp161948 150*2175Sjp161948Always use ephemeral (temporary) RSA key when doing RSA operations 151*2175Sjp161948(see L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>). 152*2175Sjp161948According to the specifications this is only done, when a RSA key 153*2175Sjp161948can only be used for signature operations (namely under export ciphers 154*2175Sjp161948with restricted RSA keylength). By setting this option, ephemeral 155*2175Sjp161948RSA keys are always used. This option breaks compatibility with the 156*2175Sjp161948SSL/TLS specifications and may lead to interoperability problems with 157*2175Sjp161948clients and should therefore never be used. Ciphers with EDH (ephemeral 158*2175Sjp161948Diffie-Hellman) key exchange should be used instead. 159*2175Sjp161948 160*2175Sjp161948=item SSL_OP_CIPHER_SERVER_PREFERENCE 161*2175Sjp161948 162*2175Sjp161948When choosing a cipher, use the server's preferences instead of the client 163*2175Sjp161948preferences. When not set, the SSL server will always follow the clients 164*2175Sjp161948preferences. When set, the SSLv3/TLSv1 server will choose following its 165*2175Sjp161948own preferences. Because of the different protocol, for SSLv2 the server 166*2175Sjp161948will send its list of preferences to the client and the client chooses. 167*2175Sjp161948 168*2175Sjp161948=item SSL_OP_PKCS1_CHECK_1 169*2175Sjp161948 170*2175Sjp161948... 171*2175Sjp161948 172*2175Sjp161948=item SSL_OP_PKCS1_CHECK_2 173*2175Sjp161948 174*2175Sjp161948... 175*2175Sjp161948 176*2175Sjp161948=item SSL_OP_NETSCAPE_CA_DN_BUG 177*2175Sjp161948 178*2175Sjp161948If we accept a netscape connection, demand a client cert, have a 179*2175Sjp161948non-self-signed CA which does not have its CA in netscape, and the 180*2175Sjp161948browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta 181*2175Sjp161948 182*2175Sjp161948=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG 183*2175Sjp161948 184*2175Sjp161948... 185*2175Sjp161948 186*2175Sjp161948=item SSL_OP_NO_SSLv2 187*2175Sjp161948 188*2175Sjp161948Do not use the SSLv2 protocol. 189*2175Sjp161948 190*2175Sjp161948=item SSL_OP_NO_SSLv3 191*2175Sjp161948 192*2175Sjp161948Do not use the SSLv3 protocol. 193*2175Sjp161948 194*2175Sjp161948=item SSL_OP_NO_TLSv1 195*2175Sjp161948 196*2175Sjp161948Do not use the TLSv1 protocol. 197*2175Sjp161948 198*2175Sjp161948=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION 199*2175Sjp161948 200*2175Sjp161948When performing renegotiation as a server, always start a new session 201*2175Sjp161948(i.e., session resumption requests are only accepted in the initial 202*2175Sjp161948handshake). This option is not needed for clients. 203*2175Sjp161948 204*2175Sjp161948=back 205*2175Sjp161948 206*2175Sjp161948=head1 RETURN VALUES 207*2175Sjp161948 208*2175Sjp161948SSL_CTX_set_options() and SSL_set_options() return the new options bitmask 209*2175Sjp161948after adding B<options>. 210*2175Sjp161948 211*2175Sjp161948SSL_CTX_get_options() and SSL_get_options() return the current bitmask. 212*2175Sjp161948 213*2175Sjp161948=head1 SEE ALSO 214*2175Sjp161948 215*2175Sjp161948L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, 216*2175Sjp161948L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, 217*2175Sjp161948L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 218*2175Sjp161948L<dhparam(1)|dhparam(1)> 219*2175Sjp161948 220*2175Sjp161948=head1 HISTORY 221*2175Sjp161948 222*2175Sjp161948B<SSL_OP_CIPHER_SERVER_PREFERENCE> and 223*2175Sjp161948B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> have been added in 224*2175Sjp161948OpenSSL 0.9.7. 225*2175Sjp161948 226*2175Sjp161948B<SSL_OP_TLS_ROLLBACK_BUG> has been added in OpenSSL 0.9.6 and was automatically 227*2175Sjp161948enabled with B<SSL_OP_ALL>. As of 0.9.7, it is no longer included in B<SSL_OP_ALL> 228*2175Sjp161948and must be explicitly set. 229*2175Sjp161948 230*2175Sjp161948B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e. 231*2175Sjp161948Versions up to OpenSSL 0.9.6c do not include the countermeasure that 232*2175Sjp161948can be disabled with this option (in OpenSSL 0.9.6d, it was always 233*2175Sjp161948enabled). 234*2175Sjp161948 235*2175Sjp161948=cut 236