src/third_party/tlslite/tlslite/integration/ClientHelper.py

   1 """
   2 A helper class for using TLS Lite with stdlib clients
   3 (httplib, xmlrpclib, imaplib, poplib).
   4 """
   5
   6 from tlslite.Checker import Checker
   7
   8 class 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