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