clarify docs
[openssl.git] / doc / ssl / SSL_CTX_set_options.pod
index 88304ef7edfbeaee15c10a50a8f90700c0e570e9..825a6ad9ae75cd8e78d12de1953926121cb6cd88 100644 (file)
@@ -2,7 +2,7 @@
 
 =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
 
@@ -11,31 +11,46 @@ SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - man
  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
@@ -86,7 +101,7 @@ doing a re-connect, always takes the first cipher in the cipher list.
 
 =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
 
@@ -100,17 +115,12 @@ doing a re-connect, always takes the first cipher in the cipher list.
 
 ...
 
-=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
 
@@ -118,13 +128,26 @@ All of the above bug workarounds.
 
 =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
@@ -133,8 +156,8 @@ 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 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
@@ -155,7 +178,7 @@ When choosing a cipher, use the server's preferences instead of the client
 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
 
@@ -168,7 +191,7 @@ will send his list of preferences to the client and the client chooses.
 =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
@@ -187,15 +210,77 @@ Do not use the SSLv3 protocol.
 
 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)>,
@@ -205,8 +290,23 @@ 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.
+
+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