/gdata/tlslite/integration/XMLRPCTransport.py

  1"""TLS Lite + xmlrpclib."""
  2
  3import xmlrpclib
  4import httplib
  5from gdata.tlslite.integration.HTTPTLSConnection import HTTPTLSConnection
  6from gdata.tlslite.integration.ClientHelper import ClientHelper
  7
  8
  9class XMLRPCTransport(xmlrpclib.Transport, ClientHelper):
 10    """Handles an HTTPS transaction to an XML-RPC server."""
 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        """Create a new XMLRPCTransport.
 20
 21        An instance of this class can be passed to L{xmlrpclib.ServerProxy}
 22        to use TLS with XML-RPC calls::
 23
 24            from tlslite.api import XMLRPCTransport
 25            from xmlrpclib import ServerProxy
 26
 27            transport = XMLRPCTransport(user="alice", password="abra123")
 28            server = ServerProxy("https://localhost", transport)
 29
 30        For client authentication, use one of these argument
 31        combinations:
 32         - username, password (SRP)
 33         - username, sharedKey (shared-key)
 34         - certChain, privateKey (certificate)
 35
 36        For server authentication, you can either rely on the
 37        implicit mutual authentication performed by SRP or
 38        shared-keys, or you can do certificate-based server
 39        authentication with one of these argument combinations:
 40         - cryptoID[, protocol] (requires cryptoIDlib)
 41         - x509Fingerprint
 42         - x509TrustList[, x509CommonName] (requires cryptlib_py)
 43
 44        Certificate-based server authentication is compatible with
 45        SRP or certificate-based client authentication.  It is
 46        not compatible with shared-keys.
 47
 48        The constructor does not perform the TLS handshake itself, but
 49        simply stores these arguments for later.  The handshake is
 50        performed only when this class needs to connect with the
 51        server.  Thus you should be prepared to handle TLS-specific
 52        exceptions when calling methods of L{xmlrpclib.ServerProxy}.  See the
 53        client handshake functions in
 54        L{tlslite.TLSConnection.TLSConnection} for details on which
 55        exceptions might be raised.
 56
 57        @type username: str
 58        @param username: SRP or shared-key username.  Requires the
 59        'password' or 'sharedKey' argument.
 60
 61        @type password: str
 62        @param password: SRP password for mutual authentication.
 63        Requires the 'username' argument.
 64
 65        @type sharedKey: str
 66        @param sharedKey: Shared key for mutual authentication.
 67        Requires the 'username' argument.
 68
 69        @type certChain: L{tlslite.X509CertChain.X509CertChain} or
 70        L{cryptoIDlib.CertChain.CertChain}
 71        @param certChain: Certificate chain for client authentication.
 72        Requires the 'privateKey' argument.  Excludes the SRP or
 73        shared-key related arguments.
 74
 75        @type privateKey: L{tlslite.utils.RSAKey.RSAKey}
 76        @param privateKey: Private key for client authentication.
 77        Requires the 'certChain' argument.  Excludes the SRP or
 78        shared-key related arguments.
 79
 80        @type cryptoID: str
 81        @param cryptoID: cryptoID for server authentication.  Mutually
 82        exclusive with the 'x509...' arguments.
 83
 84        @type protocol: str
 85        @param protocol: cryptoID protocol URI for server
 86        authentication.  Requires the 'cryptoID' argument.
 87
 88        @type x509Fingerprint: str
 89        @param x509Fingerprint: Hex-encoded X.509 fingerprint for
 90        server authentication.  Mutually exclusive with the 'cryptoID'
 91        and 'x509TrustList' arguments.
 92
 93        @type x509TrustList: list of L{tlslite.X509.X509}
 94        @param x509TrustList: A list of trusted root certificates.  The
 95        other party must present a certificate chain which extends to
 96        one of these root certificates.  The cryptlib_py module must be
 97        installed to use this parameter.  Mutually exclusive with the
 98        'cryptoID' and 'x509Fingerprint' arguments.
 99
100        @type x509CommonName: str
101        @param x509CommonName: The end-entity certificate's 'CN' field
102        must match this value.  For a web server, this is typically a
103        server name such as 'www.amazon.com'.  Mutually exclusive with
104        the 'cryptoID' and 'x509Fingerprint' arguments.  Requires the
105        'x509TrustList' argument.
106
107        @type settings: L{tlslite.HandshakeSettings.HandshakeSettings}
108        @param settings: Various settings which can be used to control
109        the ciphersuites, certificate types, and SSL/TLS versions
110        offered by the client.
111        """
112
113        ClientHelper.__init__(self,
114                 username, password, sharedKey,
115                 certChain, privateKey,
116                 cryptoID, protocol,
117                 x509Fingerprint,
118                 x509TrustList, x509CommonName,
119                 settings)
120
121
122    def make_connection(self, host):
123        # create a HTTPS connection object from a host descriptor
124        host, extra_headers, x509 = self.get_host_info(host)
125        http = HTTPTLSConnection(host, None,
126                                 self.username, self.password,
127                                 self.sharedKey,
128                                 self.certChain, self.privateKey,
129                                 self.checker.cryptoID,
130                                 self.checker.protocol,
131                                 self.checker.x509Fingerprint,
132                                 self.checker.x509TrustList,
133                                 self.checker.x509CommonName,
134                                 self.settings)
135        http2 = httplib.HTTP()
136        http2._setup(http)
137        return http2