src/third_party/tlslite/tlslite/integration/SMTP_TLS.py

   1 """TLS Lite + smtplib."""
   2
   3 from smtplib import SMTP
   4 from tlslite.TLSConnection import TLSConnection
   5 from tlslite.integration.ClientHelper import ClientHelper
   6
   7 class SMTP_TLS(SMTP):
   8     """This class extends L{smtplib.SMTP} with TLS support."""
   9
  10     def starttls(self,
  11                  username=None, password=None, sharedKey=None,
  12                  certChain=None, privateKey=None,
  13                  cryptoID=None, protocol=None,
  14                  x509Fingerprint=None,
  15                  x509TrustList=None, x509CommonName=None,
  16                  settings=None):
  17         """Puts the connection to the SMTP server into TLS mode.
  18
  19         If the server supports TLS, this will encrypt the rest of the SMTP
  20         session.
  21
  22         For client authentication, use one of these argument
  23         combinations:
  24          - username, password (SRP)
  25          - username, sharedKey (shared-key)
  26          - certChain, privateKey (certificate)
  27
  28         For server authentication, you can either rely on the
  29         implicit mutual authentication performed by SRP or
  30         shared-keys, or you can do certificate-based server
  31         authentication with one of these argument combinations:
  32          - cryptoID[, protocol] (requires cryptoIDlib)
  33          - x509Fingerprint
  34          - x509TrustList[, x509CommonName] (requires cryptlib_py)
  35
  36         Certificate-based server authentication is compatible with
  37         SRP or certificate-based client authentication.  It is
  38         not compatible with shared-keys.
  39
  40         The caller should be prepared to handle TLS-specific
  41         exceptions.  See the client handshake functions in
  42         L{tlslite.TLSConnection.TLSConnection} for details on which
  43         exceptions might be raised.
  44
  45         @type username: str
  46         @param username: SRP or shared-key username.  Requires the
  47         'password' or 'sharedKey' argument.
  48
  49         @type password: str
  50         @param password: SRP password for mutual authentication.
  51         Requires the 'username' argument.
  52
  53         @type sharedKey: str
  54         @param sharedKey: Shared key for mutual authentication.
  55         Requires the 'username' argument.
  56
  57         @type certChain: L{tlslite.X509CertChain.X509CertChain} or
  58         L{cryptoIDlib.CertChain.CertChain}
  59         @param certChain: Certificate chain for client authentication.
  60         Requires the 'privateKey' argument.  Excludes the SRP or
  61         shared-key related arguments.
  62
  63         @type privateKey: L{tlslite.utils.RSAKey.RSAKey}
  64         @param privateKey: Private key for client authentication.
  65         Requires the 'certChain' argument.  Excludes the SRP or
  66         shared-key related arguments.
  67
  68         @type cryptoID: str
  69         @param cryptoID: cryptoID for server authentication.  Mutually
  70         exclusive with the 'x509...' arguments.
  71
  72         @type protocol: str
  73         @param protocol: cryptoID protocol URI for server
  74         authentication.  Requires the 'cryptoID' argument.
  75
  76         @type x509Fingerprint: str
  77         @param x509Fingerprint: Hex-encoded X.509 fingerprint for
  78         server authentication.  Mutually exclusive with the 'cryptoID'
  79         and 'x509TrustList' arguments.
  80
  81         @type x509TrustList: list of L{tlslite.X509.X509}
  82         @param x509TrustList: A list of trusted root certificates.  The
  83         other party must present a certificate chain which extends to
  84         one of these root certificates.  The cryptlib_py module must be
  85         installed to use this parameter.  Mutually exclusive with the
  86         'cryptoID' and 'x509Fingerprint' arguments.
  87
  88         @type x509CommonName: str
  89         @param x509CommonName: The end-entity certificate's 'CN' field
  90         must match this value.  For a web server, this is typically a
  91         server name such as 'www.amazon.com'.  Mutually exclusive with
  92         the 'cryptoID' and 'x509Fingerprint' arguments.  Requires the
  93         'x509TrustList' argument.
  94
  95         @type settings: L{tlslite.HandshakeSettings.HandshakeSettings}
  96         @param settings: Various settings which can be used to control
  97         the ciphersuites, certificate types, and SSL/TLS versions
  98         offered by the client.
  99         """
 100         (resp, reply) = self.docmd("STARTTLS")
 101         if resp == 220:
 102             helper = ClientHelper(
 103                      username, password, sharedKey,
 104                      certChain, privateKey,
 105                      cryptoID, protocol,
 106                      x509Fingerprint,
 107                      x509TrustList, x509CommonName,
 108                      settings)
 109             conn = TLSConnection(self.sock)
 110             conn.closeSocket = True
 111             helper._handshake(conn)
 112             self.sock = conn
 113             self.file = conn.makefile('rb')
 114         return (resp, reply)