tlslite.integration.TLSTwistedProtocolWrapper.TLSTwistedProtocolWrapper

Package tlslite :: Package integration :: Module TLSTwistedProtocolWrapper :: Class TLSTwistedProtocolWrapper |
[show private | hide private]
[frames | no frames]

## Class TLSTwistedProtocolWrapper

       AsyncStateMachine --+
                           |
    BaseProtocol --+       |
                   |       |
            Protocol --+   |
                       |   |
         ProtocolWrapper --+
                           |
                          TLSTwistedProtocolWrapper

This class can wrap Twisted protocols to add TLS support.

Below is a complete example of using TLS Lite with a Twisted echo server.

There are two server implementations below. Echo is the original protocol, which is oblivious to TLS. Echo1 subclasses Echo and negotiates TLS when the client connects. Echo2 subclasses Echo and negotiates TLS when the client sends "STARTTLS":

       from twisted.internet.protocol import Protocol, Factory
       from twisted.internet import reactor
       from twisted.protocols.policies import WrappingFactory
       from twisted.protocols.basic import LineReceiver
       from twisted.python import log
       from twisted.python.failure import Failure
       import sys
       from tlslite.api import *

       s = open("./serverX509Cert.pem").read()
       x509 = X509()
       x509.parse(s)
       certChain = X509CertChain([x509])

       s = open("./serverX509Key.pem").read()
       privateKey = parsePEMKey(s, private=True)

       verifierDB = VerifierDB("verifierDB")
       verifierDB.open()

       class Echo(LineReceiver):
           def connectionMade(self):
               self.transport.write("Welcome to the echo server!\r\n")

           def lineReceived(self, line):
               self.transport.write(line + "\r\n")

       class Echo1(Echo):
           def connectionMade(self):
               if not self.transport.tlsStarted:
                   self.transport.setServerHandshakeOp(certChain=certChain,
                                                       privateKey=privateKey,
                                                       verifierDB=verifierDB)
               else:
                   Echo.connectionMade(self)

           def connectionLost(self, reason):
               pass #Handle any TLS exceptions here

       class Echo2(Echo):
           def lineReceived(self, data):
               if data == "STARTTLS":
                   self.transport.setServerHandshakeOp(certChain=certChain,
                                                       privateKey=privateKey,
                                                       verifierDB=verifierDB)
               else:
                   Echo.lineReceived(self, data)

           def connectionLost(self, reason):
               pass #Handle any TLS exceptions here

       factory = Factory()
       factory.protocol = Echo1
       #factory.protocol = Echo2

       wrappingFactory = WrappingFactory(factory)
       wrappingFactory.protocol = TLSTwistedProtocolWrapper

       log.startLogging(sys.stdout)
       reactor.listenTCP(1079, wrappingFactory)
       reactor.run()

This class works as follows:

Data comes in and is given to the AsyncStateMachine for handling. AsyncStateMachine will forward events to this class, and we'll pass them on to the ProtocolHandler, which will proxy them to the wrapped protocol. The wrapped protocol may then call back into this class, and these calls will be proxied into the AsyncStateMachine.

The call graph looks like this:

- self.dataReceived
  - AsyncStateMachine.inReadEvent
    - self.out(Connect|Close|Read)Event

      - ProtocolWrapper.(connectionMade|loseConnection|dataReceived)

        - self.(loseConnection|write|writeSequence)
          - AsyncStateMachine.(setCloseOp|setWriteOp)

Method Summary
| `__init__(self, factory, wrappedProtocol)`
| `connectionLost(self, reason)`
| ``connectionMade`(self)` Called when a connection is made.
| ``dataReceived`(self, data)` Called whenever data is received.
| `loseConnection(self)`
| ``outCloseEvent`(self)` Called when a close operation completes.
| ``outConnectEvent`(self)` Called when a handshake operation completes.
| `outReadEvent(self, data)`
| ``setServerHandshakeOp`(self, **args)` Start a handshake operation.
| `write(self, data)`
| `writeSequence(self, seq)`
Inherited from ProtocolWrapper
| ``__getattr__`(self, name)`
| ``getHost`(self)`
| ``getPeer`(self)`
| ``makeConnection`(self, transport)` Make a connection to a transport and a server.
| ``registerProducer`(self, producer, streaming)`
| ``stopConsuming`(self)`
| ``unregisterProducer`(self)`
Inherited from Protocol
| ``connectionFailed`(self)` (Deprecated)
Inherited from AsyncStateMachine
| ``inReadEvent`(self)` Tell the state machine it can read from the socket.
| ``inWriteEvent`(self)` Tell the state machine it can write to the socket.
| ``outWriteEvent`(self)` Called when a write operation completes.
| ``setCloseOp`(self)` Start a close operation.
| ``setHandshakeOp`(self, handshaker)` Start a handshake operation.
| ``setWriteOp`(self, writeBuffer)` Start a write operation.
bool or None | ``wantsReadEvent`(self)` If the state machine wants to read.
bool or None | ``wantsWriteEvent`(self)` If the state machine wants to write.
| ``_checkAssert`(self, maxActive)`
| ``_clear`(self)`
| ``_doCloseOp`(self)`
| ``_doHandshakeOp`(self)`
| ``_doReadOp`(self)`
| ``_doWriteOp`(self)`

Class Variable Summary
Inherited from ProtocolWrapper
`tuple` | `__implements__` = `(<class 'twisted.internet.interfaces.IT...`
`int` | `disconnecting` = 0
Inherited from BaseProtocol
`int` | `connected` = 0
`NoneType` | `transport` = None

Method Details

### connectionMade(self) Called when a connection is made. This may be considered the initializer of the protocol, because it is called when the connection is completed. For clients, this is called once the connection to the server has been established; for servers, this is called after an accept() call stops blocking and a socket has been received. If you need to send any greeting or initial message, do it here. Overrides: `twisted.protocols.policies.ProtocolWrapper.connectionMade` (inherited documentation)

### dataReceived(self, data) Called whenever data is received. Use this method to translate to a higher-level message. Usually, some callback will be made upon the receipt of each complete protocol message. Parameters: `data` - a string of indeterminate length. Please keep in mind that you will probably need to buffer some data, as partial (or multiple) protocol messages may be received! I recommend that unit tests for protocols call through to this method with differing chunk sizes, down to one byte at a time. Overrides: `twisted.protocols.policies.ProtocolWrapper.dataReceived` (inherited documentation)

### outCloseEvent(self) Called when a close operation completes. May be overridden in subclass. Overrides: `tlslite.integration.AsyncStateMachine.AsyncStateMachine.outCloseEvent` (inherited documentation)

### outConnectEvent(self) Called when a handshake operation completes. May be overridden in subclass. Overrides: `tlslite.integration.AsyncStateMachine.AsyncStateMachine.outConnectEvent` (inherited documentation)

### setServerHandshakeOp(self, **args) Start a handshake operation. The arguments passed to this function will be forwarded to `tlslite.TLSConnection.TLSConnection.handshakeServerAsync`. Overrides: `tlslite.integration.AsyncStateMachine.AsyncStateMachine.setServerHandshakeOp` (inherited documentation)

Generated by Epydoc 2.0 on Mon Feb 21 21:56:56 2005 | http://epydoc.sf.net