=head1 DESCRIPTION
SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>.
-Options already set before are not cleared.
+Options already set before are not cleared!
SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>.
-Options already set before are not cleared.
+Options already set before are not cleared!
SSL_CTX_get_options() returns the options set for B<ctx>.
The options are coded as bitmasks and can be combined by a logical B<or>
operation (|). Options can only be added but can never be reset.
-During a handshake, the option settings of the SSL object used. When
+SSL_CTX_set_options() and SSL_set_options() affect the (external)
+protocol behaviour of the SSL library. The (internal) behaviour of
+the API can be changed by using the similar
+L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> and SSL_set_mode() functions.
+
+During a handshake, the option settings of the SSL object are used. When
a new SSL object is created from a context using SSL_new(), the current
option setting is copied. Changes to B<ctx> do not affect already created
SSL objects. SSL_clear() does not affect the settings.
...
-=item SSL_OP_TLS_ROLLBACK_BUG
-
-Disable version rollback attack detection.
+=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
-During the client key exchange, the client must send the same information
-about acceptable SSL/TLS protocol levels as during the first hello. Some
-clients violate this rule by adapting to the server's answer. (Example:
-the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
-only understands up to SSLv3. In this case the client must still use the
-same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
-to the server's answer and violate the version rollback protection.)
+Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol
+vulnerability affecting CBC ciphers, which cannot be handled by some
+broken SSL implementations. This option has no effect for connections
+using other ciphers.
=item SSL_OP_ALL
=back
-It is save and recommended to use SSL_OP_ALL to enable the bug workaround
-options.
+It is usually safe to use B<SSL_OP_ALL> to enable the bug workaround
+options if compatibility with somewhat broken implementations is
+desired.
The following B<modifying> options are available:
=over 4
+=item SSL_OP_TLS_ROLLBACK_BUG
+
+Disable version rollback attack detection.
+
+During the client key exchange, the client must send the same information
+about acceptable SSL/TLS protocol levels as during the first hello. Some
+clients violate this rule by adapting to the server's answer. (Example:
+the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
+only understands up to SSLv3. In this case the client must still use the
+same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
+to the server's answer and violate the version rollback protection.)
+
=item SSL_OP_SINGLE_DH_USE
-Always create a new key when using temporary DH parameters
+Always create a new key when using temporary/ephemeral DH parameters
(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>).
+This option must be used to prevent small subgroup attacks, when
+the DH parameters were not generated using "strong" primes
+(e.g. when using DSA-parameters, see L<dhparam(1)|dhparam(1)>).
+If "strong" primes were used, it is not strictly necessary to generate
+a new DH key during each handshake but it is also recommended.
+B<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever
+temporary/ephemeral DH parameters are used.
=item SSL_OP_EPHEMERAL_RSA
-Also use ephemeral (temporary) RSA key when doing RSA operations
+Always use ephemeral (temporary) RSA key when doing RSA operations
(see L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>).
+According to the specifications this is only done, when a RSA key
+can only be used for signature operations (namely under export ciphers
+with restricted RSA keylength). By setting this option, ephemeral
+RSA keys are always used. This option breaks compatibility with the
+SSL/TLS specifications and may lead to interoperability problems with
+clients and should therefore never be used. Ciphers with EDH (ephemeral
+Diffie-Hellman) key exchange should be used instead.
=item SSL_OP_CIPHER_SERVER_PREFERENCE
non-self-sighed CA which does not have it's CA in netscape, and the
browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta
-=item SSL_OP_NON_EXPORT_FIRST
-
-On servers try to use non-export (stronger) ciphers first. This option does
-not work under all circumstances (in the code it is declared "broken").
-
=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
...
Do not use the TLSv1 protocol.
+=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
+
+When performing renegotiation as a server, always start a new session
+(i.e., session resumption requests are only accepted in the initial
+handshake). This option is not needed for clients.
+
=back
=head1 RETURN VALUES
L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,
L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>,
-L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>
+L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>,
+L<dhparam(1)|dhparam(1)>
=head1 HISTORY
-SSL_OP_CIPHER_SERVER_PREFERENCE has been added in OpenSSL 0.9.7.
+B<SSL_OP_CIPHER_SERVER_PREFERENCE> and
+B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> have been added in
+OpenSSL 0.9.7.
+
+B<SSL_OP_TLS_ROLLBACK_BUG> has been added in OpenSSL 0.9.6 and was automatically
+enabled with B<SSL_OP_ALL>. As of 0.9.7, it is no longer included in B<SSL_OP_ALL>
+and must be explicitly set.
-SSL_OP_TLS_ROLLBACK_BUG has been added in OpenSSL 0.9.6.
+B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e.
+Versions up to OpenSSL 0.9.6c do not include the countermeasure that
+can be disabled with this option (in OpenSSL 0.9.6d, it was always
+enabled).
=cut
projects / openssl.git / blobdiff