diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2010-01-27 17:46:24 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2010-01-27 17:46:24 +0000 |
commit | 99b36a8c313e6e7153bb49d6e4fa24e4ce150f59 (patch) | |
tree | fea6210a021302bd1f1c0fe08f91699381276ca9 /doc/ssl | |
parent | 89e56aebefa5476f6bffbb0f378a9a3f9d77898d (diff) |
update documentation to reflect new renegotiation options
Diffstat (limited to 'doc/ssl')
-rw-r--r-- | doc/ssl/SSL_CTX_set_options.pod | 69 |
1 files changed, 46 insertions, 23 deletions
diff --git a/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod index 9331e67153..7ffe948112 100644 --- 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. -=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 -this option +these options. =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 -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>. -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 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 @@ -306,7 +328,8 @@ enabled). 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 |