823409 - Allow application to override criteria for TLS False Start

Status: RESOLVED WONTFIX

(NSS :: Libraries, enhancement)

Description

[Brian Smith (:briansmith, :bsmith, use NEEDINFO?)]

I propose that we WONTFIX bug 820705 (which proposes adding new options to control whether NPN and/or ephemeral key exchange are required for false start) in favor of a more general mechanism where the application can register a callback that is used to determine whether we false start.

The proposed API would be:

/* EXPERIMENTAL
**
** TLS False start is a mode where a TLS client will start sending application
** data before verifying the server's Finished message, described in
** http://tools.ietf.org/html/draft-bmoeller-tls-falsestart-00. Note that
** that document's security considerations and compatibility notes are
** incomplete.
**
** SSL_FalseStartCallback enables False Start for the connection where the
** decision on whether to false start or wait for the peer's finished message
** is made by the given callback. The SSL_CanFalseStart function uses the
** minimum recommended criteria to use for enabling False Start. It is highly
** recommended that application-provided callbacks only call SSL_CanFalseStart
** and only further restrict the cases where False Start is is enabled.
**
** If the callback returns SECSuccess and sets *canFalseStart set, then
** a false start will be done; if the callback returns SECSuccess with
** *canFalseStart unset (0), then a normal handshake will be done; otherwise,
** the handshake will fail (the callback must set the error code by calling
** PR_SetError before returning SECFailure). The callback should never return
** SECWouldBlock; SECWouldBlock may be used in future versions 
** as-yet-unspecified semantics.
**
** If libbsl determines that False Start is not safe or not useful then the
** callback may not be called at all during a handshake. When it is called, the
** callback will be called once before the integrity of the handshake has been
** confirmed (after the peer's ServerHelloDone message is received, after the
** peer's certificate has been validated, and before any application data
** is sent); the contents of messages received from the peer before the
** callback is called are available to the callback (in particular, the peer's
** certificate and certificate status messages). Functions that return
** information about the negotiated connection (SSL_GetChannelInfo,
** SSL_HandshakeNegotiatedExtension, SSL_PeerCertificate, etc.) may be called
** from within the callback.
**
** SSL_FalseStartCallback and the deprecated SSL_ENABLE_FALSE_START option are
** mutually exclusive, and the time at which the HandshakeCallback is called
** differs in a very significant way depending which mechanism is used to
** enable False Start. See the documentation for SSL_HandshakeCallback for more
** information.
*/
typedef SECStatus (*SSLFalseStartCallback)(PRFileDesc * fd,
                                           void *arg,
                                           PRBool * canFalseStart);
SECStatus SSL_FalseStartCallback(SSLFalseStartCallback callback,
                                 void *cbArg);

...

/*
** Set the callback on a particular socket that gets called when we
** finish performing a handshake.
**
** When false start is disabled, or when SSL_FalseStartCallback is
** used to enable False Start, the callback will be called after the
** integrity of the handshake has been confirmed (after the peer's
** Finished message has been received.)
**
** When false start is enabled via the deprecated SSL_ENABLE_FALSE_START
** option, then when a false start is done, the handshake callback will
** be called *before* the integrity of the handshake has been confirmed
** (after the peer's ServerHelloDone message is received and before any 
** application data is sent); the contents of messages received from the
** peer before the callback is called are available to the callback (in 
** particular, the peer's certificate and certificate status messages
** are available).
*/
typedef void (PR_CALLBACK *SSLHandshakeCallback)(PRFileDesc *fd,
                                                 void *client_data);
SSL_IMPORT SECStatus SSL_HandshakeCallback(PRFileDesc *fd, 
			                   SSLHandshakeCallback cb,
					   void *client_data);

....
					   
#define SSL_ENABLE_FALSE_START         22 /* (DEPRECATED - See               */
                                          /* SSL_FalseStartCallback.) Enable */
					  /* SSL false start (off by default,*/
					  /* applies only to                 */
                                          /* clients).                       */

Comment 1

[Patrick McManus [:mcmanus]]

the proposal here is incorporated into 713933