/gdata/tlslite/integration/ClientHelper.py

  1"""
  2A helper class for using TLS Lite with stdlib clients
  3(httplib, xmlrpclib, imaplib, poplib).
  4"""
  5
  6from gdata.tlslite.Checker import Checker
  7
  8class ClientHelper:
  9    """This is a helper class used to integrate TLS Lite with various
 10    TLS clients (e.g. poplib, smtplib, httplib, etc.)"""
 11
 12    def __init__(self,
 13              username=None, password=None, sharedKey=None,
 14              certChain=None, privateKey=None,
 15              cryptoID=None, protocol=None,
 16              x509Fingerprint=None,
 17              x509TrustList=None, x509CommonName=None,
 18              settings = None):
 19        """
 20        For client authentication, use one of these argument
 21        combinations:
 22         - username, password (SRP)
 23         - username, sharedKey (shared-key)
 24         - certChain, privateKey (certificate)
 25
 26        For server authentication, you can either rely on the
 27        implicit mutual authentication performed by SRP or
 28        shared-keys, or you can do certificate-based server
 29        authentication with one of these argument combinations:
 30         - cryptoID[, protocol] (requires cryptoIDlib)
 31         - x509Fingerprint
 32         - x509TrustList[, x509CommonName] (requires cryptlib_py)
 33
 34        Certificate-based server authentication is compatible with
 35        SRP or certificate-based client authentication.  It is
 36        not compatible with shared-keys.
 37
 38        The constructor does not perform the TLS handshake itself, but
 39        simply stores these arguments for later.  The handshake is
 40        performed only when this class needs to connect with the
 41        server.  Then you should be prepared to handle TLS-specific
 42        exceptions.  See the client handshake functions in
 43        L{tlslite.TLSConnection.TLSConnection} for details on which
 44        exceptions might be raised.
 45
 46        @type username: str
 47        @param username: SRP or shared-key username.  Requires the
 48        'password' or 'sharedKey' argument.
 49
 50        @type password: str
 51        @param password: SRP password for mutual authentication.
 52        Requires the 'username' argument.
 53
 54        @type sharedKey: str
 55        @param sharedKey: Shared key for mutual authentication.
 56        Requires the 'username' argument.
 57
 58        @type certChain: L{tlslite.X509CertChain.X509CertChain} or
 59        L{cryptoIDlib.CertChain.CertChain}
 60        @param certChain: Certificate chain for client authentication.
 61        Requires the 'privateKey' argument.  Excludes the SRP or
 62        shared-key related arguments.
 63
 64        @type privateKey: L{tlslite.utils.RSAKey.RSAKey}
 65        @param privateKey: Private key for client authentication.
 66        Requires the 'certChain' argument.  Excludes the SRP or
 67        shared-key related arguments.
 68
 69        @type cryptoID: str
 70        @param cryptoID: cryptoID for server authentication.  Mutually
 71        exclusive with the 'x509...' arguments.
 72
 73        @type protocol: str
 74        @param protocol: cryptoID protocol URI for server
 75        authentication.  Requires the 'cryptoID' argument.
 76
 77        @type x509Fingerprint: str
 78        @param x509Fingerprint: Hex-encoded X.509 fingerprint for
 79        server authentication.  Mutually exclusive with the 'cryptoID'
 80        and 'x509TrustList' arguments.
 81
 82        @type x509TrustList: list of L{tlslite.X509.X509}
 83        @param x509TrustList: A list of trusted root certificates.  The
 84        other party must present a certificate chain which extends to
 85        one of these root certificates.  The cryptlib_py module must be
 86        installed to use this parameter.  Mutually exclusive with the
 87        'cryptoID' and 'x509Fingerprint' arguments.
 88
 89        @type x509CommonName: str
 90        @param x509CommonName: The end-entity certificate's 'CN' field
 91        must match this value.  For a web server, this is typically a
 92        server name such as 'www.amazon.com'.  Mutually exclusive with
 93        the 'cryptoID' and 'x509Fingerprint' arguments.  Requires the
 94        'x509TrustList' argument.
 95
 96        @type settings: L{tlslite.HandshakeSettings.HandshakeSettings}
 97        @param settings: Various settings which can be used to control
 98        the ciphersuites, certificate types, and SSL/TLS versions
 99        offered by the client.
100        """
101
102        self.username = None
103        self.password = None
104        self.sharedKey = None
105        self.certChain = None
106        self.privateKey = None
107        self.checker = None
108
109        #SRP Authentication
110        if username and password and not \
111                (sharedKey or certChain or privateKey):
112            self.username = username
113            self.password = password
114
115        #Shared Key Authentication
116        elif username and sharedKey and not \
117                (password or certChain or privateKey):
118            self.username = username
119            self.sharedKey = sharedKey
120
121        #Certificate Chain Authentication
122        elif certChain and privateKey and not \
123                (username or password or sharedKey):
124            self.certChain = certChain
125            self.privateKey = privateKey
126
127        #No Authentication
128        elif not password and not username and not \
129                sharedKey and not certChain and not privateKey:
130            pass
131
132        else:
133            raise ValueError("Bad parameters")
134
135        #Authenticate the server based on its cryptoID or fingerprint
136        if sharedKey and (cryptoID or protocol or x509Fingerprint):
137            raise ValueError("Can't use shared keys with other forms of"\
138                             "authentication")
139
140        self.checker = Checker(cryptoID, protocol, x509Fingerprint,
141                               x509TrustList, x509CommonName)
142        self.settings = settings
143
144        self.tlsSession = None
145
146    def _handshake(self, tlsConnection):
147        if self.username and self.password:
148            tlsConnection.handshakeClientSRP(username=self.username,
149                                             password=self.password,
150                                             checker=self.checker,
151                                             settings=self.settings,
152                                             session=self.tlsSession)
153        elif self.username and self.sharedKey:
154            tlsConnection.handshakeClientSharedKey(username=self.username,
155                                                   sharedKey=self.sharedKey,
156                                                   settings=self.settings)
157        else:
158            tlsConnection.handshakeClientCert(certChain=self.certChain,
159                                              privateKey=self.privateKey,
160                                              checker=self.checker,
161                                              settings=self.settings,
162                                              session=self.tlsSession)
163        self.tlsSession = tlsConnection.session