=head1 NAME
-SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - manipulate SSL engine options
+SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options, SSL_clear_options, SSL_CTX_get_options, SSL_get_options, SSL_get_secure_renegotiation_support - manipulate SSL options
=head1 SYNOPSIS
long SSL_CTX_set_options(SSL_CTX *ctx, long options);
long SSL_set_options(SSL *ssl, long options);
+ long SSL_CTX_clear_options(SSL_CTX *ctx, long options);
+ long SSL_clear_options(SSL *ssl, long options);
+
long SSL_CTX_get_options(SSL_CTX *ctx);
long SSL_get_options(SSL *ssl);
+ long SSL_get_secure_renegotiation_support(SSL *ssl);
+
=head1 DESCRIPTION
+Note: all these functions are implemented using macros.
+
SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>.
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!
+SSL_CTX_clear_options() clears the options set via bitmask in B<options>
+to B<ctx>.
+
+SSL_clear_options() clears the options set via bitmask in B<options> to B<ssl>.
+
SSL_CTX_get_options() returns the options set for B<ctx>.
SSL_get_options() returns the options set for B<ssl>.
+SSL_get_secure_renegotiation_support() indicates whether the peer supports
+secure renegotiation.
+
=head1 NOTES
The behaviour of the SSL library can be changed by setting several options.
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.
+operation (|).
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_modes(3)|SSL_CTX_set_modes(3)> and SSL_set_modes() functions.
+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
=item SSL_OP_MSIE_SSLV2_RSA_PADDING
-...
+As of OpenSSL 0.9.7h and 0.9.8a, this option has no effect.
=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG
...
-=item SSL_OP_TLS_ROLLBACK_BUG
+=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
-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.)
+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/ephemeral DH parameters
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 recommendet.
-SSL_OP_SINGLE_DH_USE should therefore be enabled whenever
+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
preferences. When not set, the SSL server will always follow the clients
preferences. When set, the SSLv3/TLSv1 server will choose following its
own preferences. Because of the different protocol, for SSLv2 the server
-will send his list of preferences to the client and the client chooses.
+will send its list of preferences to the client and the client chooses.
=item SSL_OP_PKCS1_CHECK_1
=item SSL_OP_NETSCAPE_CA_DN_BUG
If we accept a netscape connection, demand a client cert, have a
-non-self-sighed CA which does not have it's CA in netscape, and the
+non-self-signed CA which does not have its CA in netscape, and the
browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta
=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.
+
+=item SSL_OP_NO_TICKET
+
+Normally clients and servers will, where possible, transparently make use
+of RFC4507bis tickets for stateless session resumption.
+
+If this option is set this functionality is disabled and tickets will
+not be used by clients or servers.
+
+=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
+
+See the B<SECURE RENEGOTIATION> section for a discussion of the purpose of
+this option
+
=back
+=head1 SECURE RENEGOTIATION
+
+OpenSSL 0.9.8m and later always attempts to use secure renegotiation as
+described in draft-ietf-tls-renegotiation (FIXME: replace by RFC). This
+counters a prefix attack described in the draft and elsewhere (FIXME: need full
+reference).
+
+This attack has far reaching consequences which application writers should be
+aware of. In the description below an implementation supporting secure
+renegotiation is referred to as I<patched>. A server not supporting secure
+renegotiation is referred to as I<unpatched>.
+
+If an unpatched client attempts to connect to a patched OpenSSL server then
+the attempt will succeed but renegotiation is not permitted. As required
+by the standard a B<no_renegotiation> alert is sent back to the client if
+the TLS v1.0 protocol is used. If SSLv3.0 is used then renegotiation results
+in a fatal B<handshake_failed> alert.
+
+If a patched OpenSSL client attempts to connect to an unpatched server
+then the connection will fail because it is not possible to determine
+whether an attack is taking place.
+
+If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then the
+above restrictions are relaxed. Renegotiation is permissible and initial
+initial connections to unpatched servers will succeed.
+
+This option should be used with caution because it leaves both clients and
+servers vulnerable. However unpatched servers and clients are likely to be
+around for some time and refusing to connect to unpatched servers or denying
+renegotion altogether may be unacceptable. So applications may be forced to
+tolerate unsafe renegotiation for the immediate future.
+
+The function SSL_get_secure_renegotiation_support() indicates whether the peer
+supports secure renegotiation.
+
+The deprecated SSLv2 protocol does not support secure renegotiation at all.
+
=head1 RETURN VALUES
SSL_CTX_set_options() and SSL_set_options() return the new options bitmask
after adding B<options>.
+SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask
+after clearing B<options>.
+
SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
+SSL_get_secure_renegotiation_support() returns 1 is the peer supports
+secure renegotiation and 0 if it does not.
+
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,
=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.
+
+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).
+
+SSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL
+0.9.8m.
-SSL_OP_TLS_ROLLBACK_BUG has been added in OpenSSL 0.9.6.
+B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> was first added in OpenSSL
+0.9.8m.
=cut