From 4b38f35e720863db914c611bfbd588587dd54ea8 Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Wed, 27 Jan 2010 17:50:47 +0000 Subject: [PATCH] update documentation to reflect new renegotiation options --- doc/ssl/SSL_CTX_set_options.pod | 69 ++++++++++++++++++++++----------- 1 file changed, 46 insertions(+), 23 deletions(-) diff --git a/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod index 4bd8be17ea..531f733b3d 100644 --- a/doc/ssl/SSL_CTX_set_options.pod +++ b/doc/ssl/SSL_CTX_set_options.pod @@ -225,10 +225,10 @@ is explicitly set when OpenSSL is compiled. 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 section for a discussion of the purpose of -this option +these options. =back @@ -236,38 +236,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 -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. A server not supporting secure renegotiation is referred to as I. -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 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 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 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 warning alert if TLS v1.0 is used or a fatal +B alert in SSL v3.0. + +If the patched server attempts to renegotiate a fatal B +alert is sent. This is because the server code may be unaware of the +unpatched nature of the client. + +If the option B is set then +renegotiation B succeeds. + +B 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 alert. OpenSSL versions 0.9.8m and later will regard +a B alert as fatal and respond with a fatal +B alert. + +=head2 Patched client and unpatched server. + +If the option B 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 will +B be set by default in a future version of OpenSSL. + +Applications that want to ensure they can connect to unpatched servers should +always B B + +Applications that want to ensure they can B connect to unpatched servers +(and thus avoid any security issues) should always B +B using SSL_CTX_clear_options() or +SSL_clear_options(). 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 discouraged. =head1 RETURN VALUES @@ -307,7 +329,8 @@ enabled). SSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL 0.9.8m. -B was first added in OpenSSL -0.9.8m. +B, B +and the function SSL_get_secure_renegotiation_support() were first added in +OpenSSL 0.9.8m. =cut -- 2.25.1