update documentation to reflect new renegotiation options

diff --git a/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod
index 9331e6715338d2dd180d60bb54deca7452fa81a7..7ffe9481121c734b2c13cb0d8b8d12c30782eb0f 100644 (file)
--- a/doc/ssl/SSL_CTX_set_options.pod
+++ b/doc/ssl/SSL_CTX_set_options.pod
@@ -224,10 +224,10 @@ 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.
 
 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
+=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION, SSL_OP_LEGACY_SERVER_CONNECT

 
 See the B<SECURE RENEGOTIATION> section for a discussion of the purpose of
 
 See the B<SECURE RENEGOTIATION> section for a discussion of the purpose of

-this option
+these options.

 
 =back
 
 
 =back
 


@@ -235,38 +235,60 @@ this option
 
 OpenSSL 0.9.8m and later always attempts to use secure renegotiation as
 described in draft-ietf-tls-renegotiation (FIXME: replace by RFC). This
 
 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).
+counters the prefix attack described in CVE-2009-3555 and elsewhere.

 
 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>.
 
 
 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.
+=head2 Patched client and server

 
 

-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.
+Connections and renegotiation will always succeed.

 
 

-If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then the
-above restrictions are relaxed. Renegotiation is permissible and initial
-connections to unpatched servers will succeed.
+=head2 Unpatched client and patched server

 
 

-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 initial connection suceeds but client renegotiation is denied with a
+B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal
+B<handshake_failure> alert in SSL v3.0.
+
+If the patched server attempts to renegotiate a fatal B<handshake_failure>
+alert is sent. This is because the server code may be unaware of the
+unpatched nature of the client.
+
+If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then
+renegotiation B<always> succeeds.
+
+B<NB:> a bug in OpenSSL clients earlier than 0.9.8m (all of which are
+unpatched) will result in the connection hanging if it receives a
+B<no_renegotiation> alert. OpenSSL versions 0.9.8m and later will regard
+a B<no_renegotiation> alert as fatal and respond with a fatal
+B<handshake_failure> alert.
+
+=head2 Patched client and unpatched server.
+
+If the option B<SSL_OP_LEGACY_SERVER_CONNECT> is set then initial connections
+to unpatched servers succeed. This option is currently set by default even
+though it has security implications: otherwise it would be impossible to
+connect to unpatched servers i.e. all of them initially and this is clearly not
+acceptable.
+
+As more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will
+B<not> be set by default in a future version of OpenSSL.
+
+Applications that want to ensure they can connect to unpatched servers should
+always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT>
+
+Applications that want to ensure they can B<not> connect to unpatched servers
+(and thus avoid any security issues) should always B<clear>
+B<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or
+SSL_clear_options().

 
 The function SSL_get_secure_renegotiation_support() indicates whether the peer
 supports secure renegotiation. 
 
 
 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.
+The deprecated and highly broken SSLv2 protocol does not support secure
+renegotiation at all: its use is B<strongly> discouraged.

 
 =head1 RETURN VALUES
 
 
 =head1 RETURN VALUES
 


@@ -306,7 +328,8 @@ enabled).
 SSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL
 0.9.8m.
 
 SSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL
 0.9.8m.
 

-B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> was first added in OpenSSL
-0.9.8m.
+B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>, B<SSL_OP_LEGACY_SERVER_CONNECT>
+and the function SSL_get_secure_renegotiation_support() were first added in
+OpenSSL 0.9.8m.

 
 =cut
 
 =cut