Add an API which makes it easy to start (and stop) speaking TLS over an arbitrary transport

	@exarkun reported
Trac ID	trac#5015
Type	enhancement
Created	2011-04-03 16:28:27Z

For historical reasons, we have IReactorSSL and ITLSTransport. There was no way to implement this functionality except directly with the support of the reactor.

With twisted.protocols.tls, we now have an implementation that is independent of any TLS-specific support in the reactor. However, twisted.protocols.tls is very geared towards being used to replace IReactorSSL.connectSSL/listenSSL. It is possible to use it to replace ITLSTransport.startTLS, but:

1. It's complicated. There is an unfortunate special case in twisted.protocols.tls to deal with this (the _connectWrapped argument to TLSMemoryBIOPRotocol.__init__).
2. The very nature of ITLSTransport requires direct support from the reactor. Outside code cannot (cleanly) add a startTLS method to an arbitrary transport.

Instead, to remove the need to have support in the reactor, it would be nice to have an API like this:

    class SomeProtocol(Protocol):
        def dataReceived(self, bytes):
            if somecondition():
                tls = TLSTransport(ctx, self.transport, self)
                self.transport.switchProtocol(tls)
                self.transport = tls
                # Perhaps also...
                self.transport.handshake()

These details might even all be wrapped up inside an even simpler helper API:

    class SomeProtocol(Protocol):
        def dataReceived(self, bytes):
            if somecondition():
                self.transport = startTLS(ctx, self.transport, self)

The details might differ, but importantly an API like this can be implemented entirely outside the reactor, except for the new switchProtocol method (proposed already in #3204).

This has other nice properties.

1. Compared to the current APIs and implementation, it's easier to see how stacking works.
2. Buffering is simplified because the original transport and the TLS transport are separate objects each dealing with buffering on their own.
3. TLS shutdown without underlying transport shutdown is more obvious, since it just means going back to the original transport and discarding the TLS transport.

trac-id__5015 5015
type__enhancement enhancement
reporter__exarkun exarkun
priority__normal normal
milestone__ 
branch__ 
branch_author__ 
status__new new
resolution__None None
component__core core
keywords__ 
time__1301848107000000 1301848107000000
changetime__1340898077000000 1340898077000000
version__None None
owner__ 
cc__adiroiban

Start by reading twisted.protocols.tls and the proposed switchProtocol work in #3204. Determine how an API can layer TLS over an arbitrary transport without reactor-specific support, including protocol switching, buffering, and shutdown. Done means the design is implemented with suitable coverage for starting and stopping TLS.