Draft release notes for 2.10.0

[Simon Josefsson]

Nikos Mavrogiannopoulos <nmav at gnutls.org> writes:

> On Thu, Apr 22, 2010 at 10:17 AM, Simon Josefsson <simon at josefsson.org> wrote:
>
> Hi,
>
>> We need to write a section about the new TLS safe renegotiation support,
>> and ideas on what to write here is appreciated.  I think we need to
>> point to other documents explaining the problem, and describe what this
>> release adds to mitigate the problem.  And describe our semantics when
>> talking with old servers...
>
> A proper discussion would be more proper in the documentation rather
> in the release notes.

Yes.  I have written the section below for the manual.  Please review it
for correctness!

/Simon

3.10 Safe Renegotiation
=======================

Some application protocols and implementations uses the TLS
renegotiation feature in a manner that enables attackers to insert
content of his choice in the beginning of a TLS session.

The simplest example is HTTP.  For HTTP one attack works by having the
attacker simulate a client and connect to a server, with server-only
authentication, and send some data intended to cause harm.  When the
proper client attempts to contact the server, the attacker hijacks that
connection and uses the TLS renegotiation feature with the server and
splices in the client connection to the already established connection
between the client and server.  The attacker will not be able to read
the data exchanged between the client and the server.  However, some
server implementations will (incorrectly) assume that the data sent by
the attacker was sent by the now authenticated client.  The result is a
prefix plain-text injection attack.

While fixing these application protocols and implementations would be
one natural reaction, an extension to TLS has been designed that
cryptographically binds together any renegotiated handshakes with the
initial negotiation.  When the extension is used, the attack is
detected and the session can be terminated.  The extension is specified
in [RFC5746] (*note Bibliography::).

GnuTLS supports the safe renegotiation extension.  By default, GnuTLS
clients will attempt to negotiate the safe renegotiation extension when
talking to servers.  Also by default, GnuTLS servers will accept the
extension when presented by clients.  However, by default GnuTLS client
and servers will not refuse renegotiation attempts when the extension
has not been negotiated, as this would break backwards compatibility
and cause too much operational problems.  We will likely reconsider
these defaults in the future.

To modify the default behaviour, we have introduced three new priority
strings.  The priority strings can be used by applications (*note
gnutls_priority_set::) and end users (e.g., `--priority' parameter to
`gnutls-cli' and `gnutls-serv').

The `%UNSAFE_RENEGOTIATION' priority string requests what is today the
default behaviour, i.e., that handshakes without the safe renegotiation
extension is permitted.  To make more use of the extension, you may
provide the `%SAFE_RENEGOTIATION' priority string.  In this mode,
clients will require that the server supports the extension for the
initial handshake, and servers will require that the client supports
the extension for any renegotiated handshakes.  If you want to make a
server refuse even initial handshakes without the safe renegotiation
extension, use the `%INITIAL_SAFE_RENEGOTIATION' priority string.  It
is possible to disable use of the extension completely by using the
`%DISABLE_SAFE_RENEGOTIATION' priority string however this is strongly
discouraged!

For applications we have introduced three new APIs related to safe
renegotiation.  The *note gnutls_safe_renegotiation_status:: function is
used to check if the extension has been negotiated on a session, and
can be used both by clients and servers.  The *note
gnutls_safe_renegotiation_set:: function allows applications to request
that the extension should be disabled (or re-enabled) in handshakes for
the session.  The *note gnutls_safe_negotiation_set_initial:: function
is only relevant for servers, and is used to enforce that clients
support the extension even on the initial handshake.