Package: tlslite
tlslite version 0.4.9                                            Aug 11 2015Trevor Perrin <tlslite at trevp.net>http://trevp.net/tlslite/============================================================================Table of Contents==================1  Introduction2  License/Acknowledgements3  Installation4  Getting Started with the Command-Line Tools5  Getting Started with the Library6  Using TLS Lite with httplib7  Using TLS Lite with poplib or imaplib8  Using TLS Lite with smtplib9 Using TLS Lite with SocketServer10 Using TLS Lite with asyncore11 SECURITY CONSIDERATIONS12 History1 Introduction===============TLS Lite is an open source python library that implements SSL and TLS. TLSLite supports RSA and SRP ciphersuites. TLS Lite is pure python, however itcan use other libraries for faster crypto operations. TLS Lite integrates withseveral stdlib neworking libraries.API documentation is available in the 'docs' directory.If you have questions or feedback, feel free to contact me.  For discussingimprovements to tlslite, also see 'tlslite-dev@googlegroups.com'.2 Licenses/Acknowledgements============================TLS Lite is written (mostly) by Trevor Perrin. It includes code from BramCohen, Google, Kees Bos, Sam Rushing, Dimitris Moraitis, Marcelo Fernandez,Martin von Loewis, Dave Baggett, Yngve N. Pettersen (ported by PaulSokolovsky), Mirko Dziadzka, David Benjamin, and Hubert Kario.All code in TLS Lite has either been dedicated to the public domain by itsauthors, or placed under a BSD-style license. See the LICENSE file fordetails.Thanks to Edward Loper for Epydoc, which generated the API docs.3 Installation===============Requirements:Python 2.6 or higher is required. Python 3 is supported.Options:- If you have the M2Crypto interface to OpenSSL, this will be used for fastRSA operations and fast ciphers.- If you have pycrypto this will be used for fast RSA operations and fastciphers.- If you have the GMPY interface to GMP, this will be used for fast RSA andSRP operations.- These modules don't need to be present at installation - you can installthem any time.Run 'python setup.py install'Test the Installation:- From the distribution's ./tests subdirectory, run:./tlstest.py server localhost:4443 .- While the test server is waiting, run:./tlstest.py client localhost:4443 .If both say "Test succeeded" at the end, you're ready to go.4 Getting Started with the Command-Line Tools==============================================tlslite installs two command-line scripts: 'tlsdb.py' and 'tls.py'.'tls.py' lets you run test clients and servers. It can be used for testingother TLS implementations, or as example code. Note that 'tls.py server' runsan HTTPS server which will serve files rooted at the current directory bydefault, so be careful.'tlsdb.py' lets you manage SRP verifier databases. These databases are used bya TLS server when authenticating clients with SRP.X.509------To run an X.509 server, go to the ./tests directory and do:tls.py server -k serverX509Key.pem -c serverX509Cert.pem localhost:4443Try connecting to the server with a web browser, or with:tls.py client localhost:4443X.509 with TACK----------------To run an X.509 server using a TACK, install TACKpy, then run the same servercommand as above with added arguments:... -t TACK1.pem localhost:4443SRP----To run an SRP server, try something like:tlsdb.py createsrp verifierDBtlsdb.py add verifierDB alice abra123cadabra 1024tlsdb.py add verifierDB bob swordfish 2048tls.py server -v verifierDB localhost:4443Then try connecting to the server with:tls.py client localhost:4443 alice abra123cadabraHTTPS------To run an HTTPS server with less typing, run ./tests/httpsserver.sh.To run an HTTPS client, run ./tests/httpsclient.py.5 Getting Started with the Library===================================Whether you're writing a client or server, there are six steps:1) Create a socket and connect it to the other party.2) Construct a TLSConnection instance with the socket.3) Call a handshake function on TLSConnection to perform the TLS handshake.4) Check the results to make sure you're talking to the right party.5) Use the TLSConnection to exchange data.6) Call close() on the TLSConnection when you're done.TLS Lite also integrates with several stdlib python libraries. See thesections following this one for details.5 Step 1 - create a socket---------------------------Below demonstrates a socket connection to Amazon's secure site.from socket import *sock = socket(AF_INET, SOCK_STREAM)sock.connect( ("www.amazon.com", 443) )5 Step 2 - construct a TLSConnection-------------------------------------You can import tlslite objects individually, such as:from tlslite import TLSConnectionOr import the most useful objects through:from tlslite.api import *Then do:connection = TLSConnection(sock)5 Step 3 - call a handshake function (client)----------------------------------------------If you're a client, there's two different handshake functions you can call,depending on how you want to authenticate:connection.handshakeClientCert()connection.handshakeClientCert(certChain, privateKey)connection.handshakeClientSRP("alice", "abra123cadabra")The ClientCert function without arguments is used when connecting to a sitelike Amazon, which doesn't require client authentication, but which willauthenticate itself using an X.509 certificate chain.The ClientCert function can also be used to do client authentication with anX.509 certificate chain and corresponding private key. To use X.509 chains,you'll need some way of creating these, such as OpenSSL (seehttp://www.openssl.org/docs/HOWTO/ for details).Below is an example of loading an X.509 chain and private key:from tlslite import X509, X509CertChain, parsePEMKeys = open("./test/clientX509Cert.pem").read()x509 = X509()x509.parse(s)certChain = X509CertChain([x509])s = open("./test/clientX509Key.pem").read()privateKey = parsePEMKey(s, private=True)The SRP function does mutual authentication with a username and password - seeRFC 5054 for details.If you want more control over the handshake, you can pass in aHandshakeSettings instance. For example, if you're performing SRP, but youonly want to use SRP parameters of at least 2048 bits, and you only want touse the AES-256 cipher, and you only want to allow TLS (version 3.1), not SSL(version 3.0), you can do:settings = HandshakeSettings()settings.minKeySize = 2048settings.cipherNames = ["aes256"]settings.minVersion = (3,1)settings.useExperimentalTACKExtension = True  # Needed for TACK supportconnection.handshakeClientSRP("alice", "abra123cadabra", settings=settings)If you want to check the server's certificate using TACK, you should set the"useExperiementalTACKExtension" value in HandshakeSettings. (Eventually, TACKsupport will be enabled by default, but for now it is an experimental featurewhich relies on a temporary TLS Extension number, and should not be used forproduction software.) This will cause the client to request the server to sendyou a TACK (and/or any TACK Break Signatures):Finally, every TLSConnection has a session object. You can try to resume aprevious session by passing in the session object from the old session. If theserver remembers this old session and supports resumption, the handshake willfinish more quickly. Otherwise, the full handshake will be done. For example:connection.handshakeClientSRP("alice", "abra123cadabra")..oldSession = connection.sessionconnection2.handshakeClientSRP("alice", "abra123cadabra", session=oldSession)5 Step 3 - call a handshake function (server)----------------------------------------------If you're a server, there's only one handshake function, but you can pass itseveral different parameters, depending on which types of authenticationyou're willing to perform.To perform SRP authentication, you have to pass in a database of passwordverifiers.  The VerifierDB class manages an in-memory or on-disk verifierdatabase.verifierDB = VerifierDB("./test/verifierDB")verifierDB.open()connection.handshakeServer(verifierDB=verifierDB)To perform authentication with a certificate and private key, the server mustload these as described in the previous section, then pass them in.  If theserver sets the reqCert boolean to True, a certificate chain will be requestedfrom the client.connection.handshakeServer(certChain=certChain, privateKey=privateKey,reqCert=True)You can pass in a verifier database and/or a certificate chain+private key.The client will use one or both to authenticate the server.You can also pass in a HandshakeSettings object, as described in the lastsection, for finer control over handshaking details.If you are passing in a certificate chain+private key, you may additionallyprovide a TACK to assist the client in authenticating your certificate chain.This requires the TACKpy library. Load a TACKpy.TACK object, then do:settings = HandshakeSettings()settings.useExperimentalTACKExtension = True  # Needed for TACK supportconnection.handshakeServer(certChain=certChain, privateKey=privateKey,tack=tack, settings=settings)Finally, the server can maintain a SessionCache, which will allow clients touse session resumption:sessionCache = SessionCache()connection.handshakeServer(verifierDB=verifierDB, sessionCache=sessionCache)It should be noted that the session cache, and the verifier databases, are allthread-safe.5 Step 4 - check the results-----------------------------If the handshake completes without raising an exception, authenticationresults will be stored in the connection's session object.  The followingvariables will be populated if applicable, or else set to None:connection.session.srpUsername       # stringconnection.session.clientCertChain   # X509CertChainconnection.session.serverCertChain   # X509CertChainconnection.session.tackExt           # TACKpy.TACK_ExtensionX.509 chain objects return the end-entity fingerprint via getFingerprint(),and ignore the other certificates.TACK objects return the (validated) TACK ID via getTACKID().To save yourself the trouble of inspecting certificates after the handshake,you can pass a Checker object into the handshake function. The checker will becalled if the handshake completes successfully. If the other party isn'tapproved by the checker, a subclass of TLSAuthenticationError will be raised.If the handshake fails for any reason, including a Checker error, an exceptionwill be raised and the socket will be closed. If the socket timed out or wasunexpectedly closed, a socket.error or TLSAbruptCloseError will be raised.Otherwise, either a TLSLocalAlert or TLSRemoteAlert will be raised, dependingon whether the local or remote implementation signalled the error. Theexception object has a 'description' member which identifies the error basedon the codes in RFC 2246. A TLSLocalAlert also has a 'message' string that mayhave more details.Example of handling a remote alert:try:[...]except TLSRemoteAlert as alert:if alert.description == AlertDescription.unknown_psk_identity:print "Unknown user."[...]Below are some common alerts and their probable causes, and whether they aresignalled by the client or server.Client handshake_failure:- SRP parameters are not recognized by client- Server's TACK was unrelated to its certificate chainClient insufficient_security:- SRP parameters are too smallClient protocol_version:- Client doesn't support the server's protocol versionServer protocol_version:- Server doesn't support the client's protocol versionServer bad_record_mac:- bad SRP username or passwordServer unknown_psk_identity- bad SRP username (bad_record_mac could be used for the same thing)Server handshake_failure:- no matching cipher suites5 Step 5 - exchange data-------------------------Now that you have a connection, you can call read() and write() as if it werea socket.SSL object. You can also call send(), sendall(), recv(), andmakefile() as if it were a socket. These calls may raise TLSLocalAlert,TLSRemoteAlert, socket.error, or TLSAbruptCloseError, just like the handshakefunctions.Once the TLS connection is closed by the other side, calls to read() or recv()will return an empty string. If the socket is closed by the other side withoutfirst closing the TLS connection, calls to read() or recv() will return aTLSAbruptCloseError, and calls to write() or send() will return asocket.error.5 Step 6 - close the connection--------------------------------When you're finished sending data, you should call close() to close theconnection and socket. When the connection is closed properly, the sessionobject can be used for session resumption.If an exception is raised the connection will be automatically closed; youdon't need to call close(). Furthermore, you will probably not be able tore-use the socket, the connection object, or the session object, and youshouldn't even try.By default, calling close() will close the underlying socket. If you set theconnection's closeSocket flag to False, the socket will remain open afterclose. (NOTE: some TLS implementations will not respond properly to theclose_notify alert that close() generates, so the connection will hang ifcloseSocket is set to True.)6 Using TLS Lite with httplib==============================TLS Lite comes with an HTTPTLSConnection class that extends httplib to workover SSL/TLS connections.  Depending on how you construct it, it will dodifferent types of authentication.#No authentication whatsoeverh = HTTPTLSConnection("www.amazon.com", 443)h.request("GET", "")r = h.getresponse()[...]#Authenticate server based on its TACK IDh = HTTPTLSConnection("localhost", 4443,tackID="B3ARS.EQ61B.F34EL.9KKLN.3WEW5", hardTack=False)[...]#Mutually authenticate with SRPh = HTTPTLSConnection("localhost", 443,username="alice", password="abra123cadabra")[...]7 Using TLS Lite with poplib or imaplib========================================TLS Lite comes with POP3_TLS and IMAP4_TLS classes that extend poplib andimaplib to work over SSL/TLS connections.  These classes can be constructedwith the same parameters as HTTPTLSConnection (see previous section), andbehave similarly.#To connect to a POP3 server over SSL and display its fingerprint:from tlslite.api import *p = POP3_TLS("---------.net", port=995)print p.sock.session.serverCertChain.getFingerprint()[...]#To connect to an IMAP server once you know its fingerprint:from tlslite.api import *i = IMAP4_TLS("cyrus.andrew.cmu.edu",x509Fingerprint="00c14371227b3b677ddb9c4901e6f2aee18d3e45")[...]8 Using TLS Lite with smtplib==============================TLS Lite comes with an SMTP_TLS class that extends smtplib to workover SSL/TLS connections.  This class accepts the same parameters asHTTPTLSConnection (see previous section), and behaves similarly.  Dependingon how you call starttls(), it will do different types of authentication.#To connect to an SMTP server once you know its fingerprint:from tlslite.api import *s = SMTP_TLS("----------.net", port=587)s.ehlo()s.starttls(x509Fingerprint="7e39be84a2e3a7ad071752e3001d931bf82c32dc")[...]9 Using TLS Lite with SocketServer====================================You can use TLS Lite to implement servers using Python's SocketServerframework.  TLS Lite comes with a TLSSocketServerMixIn class.  You can combinethis with a TCPServer such as HTTPServer.  To combine them, define a new classthat inherits from both of them (with the mix-in first). Then implement thehandshake() method, doing some sort of server handshake on the connectionargument.  If the handshake method returns True, the RequestHandler will betriggered.  See the tests/httpsserver.py example.10 Using TLS Lite with asyncore================================TLS Lite can be used with subclasses of asyncore.dispatcher.  See the commentsin TLSAsyncDispatcherMixIn.py for details.  This is still experimental, andmay not work with all asyncore.dispatcher subclasses.11 Security Considerations===========================TLS Lite is beta-quality code. It hasn't received much security analysis. Useat your own risk.TLS Lite does NOT verify certificates by default.TLS Lite's pure-python ciphers are probably vulnerable to timing attacks.TLS Lite is probably vulnerable to the "Lucky 13" timing attack if AES or 3DESare used, or the weak cipher RC4 otherwise.  This unhappy situation will remainuntil TLS Lite implements authenticated-encryption ciphersuites (like GCM), orRFC 7366.12 History===========0.4.9 - 08/11/2015- Fixed denial of service (runtime exception) on malformed packet (Hubert Kario)- Fixed session caching bug (Mirko Dziadzka)- Fixed SRP spec non-compliance- Added FALLBACK_SCSV (David Benjamin)- Unit testing (Hubert Kario)- "make test" and "make test-dev" targets (Hubert Kario)0.4.8 - 11/12/2014- Added more acknowledgements and security considerations0.4.7 - 11/12/2014- Added TLS 1.2 support (Yngve Pettersen and Paul Sokolovsky)- Don't offer SSLv3 by default (e.g. POODLE)- Fixed bug with PyCrypto_RSA integration- Fixed harmless bug that added non-prime into sieves list- Added "make test" and "make test-dev" targets (Hubert Kario)0.4.5 - 3/20/2013- **API CHANGE**: TLSClosedConnectionError instead of ValueError when writingto a closed connection.  This inherits from socket.error, so shouldinteract better with SocketServer (see http://bugs.python.org/issue14574)and other things expecting a socket.error in this situation.- Added support for RC4-MD5 ciphersuite (if enabled in settings)- This is allegedly necessary to connect to some Internet servers.- Added TLSConnection.unread() function- Switched to New-style classes (inherit from 'object')- Minor cleanups0.4.4 - 2/25/2013- Added Python 3 support (Martin von Loewis)- Added NPN client support (Marcelo Fernandez)- Switched to RC4 as preferred cipher- faster in Python, avoids "Lucky 13" timing attacks- Fixed bug when specifying ciphers for anon ciphersuites- Made RSA hashAndVerify() tolerant of sigs w/o encoded NULL AlgorithmParam- (this function is not used for TLS currently, and this tolerance maynot even be necessary)0.4.3 - 9/27/2012- Minor bugfix (0.4.2 doesn't load tackpy)0.4.2 - 9/25/2012- Updated TACK (compatible with tackpy 0.9.9)0.4.1 - 5/22/2012- Fixed RSA padding bugs (w/help from John Randolph)- Updated TACK (compatible with tackpy 0.9.7)- Added SNI- Added NPN server support (Sam Rushing/Google)- Added AnonDH (Dimitris Moraitis)- Added X509CertChain.parsePemList- Improved XML-RPC (Kees Bos)0.4.0 - 2/11/2012- Fixed pycrypto support- Fixed python 2.6 problems0.3.9.x - 2/7/2012Much code cleanup, in particular decomposing the handshake functions so theyare readable. The main new feature is support for TACK, an experimentalauthentication method that provides a new way to pin server certificates (Seehttps://github.com/moxie0/Convergence/wiki/TACK ).Also:- Security Fixes- Sends SCSV ciphersuite as per RFC 5746, to signal non-renegotiatedClient Hello.  Does not support renegotiation (never has).- Change from e=3 to e=65537 for generated RSA keys, not strictlynecessary but mitigates risk of sloppy verifier.- 1/(n-1) countermeasure for BEAST.- Behavior changes:- Split cmdline into tls.py and tlstest.py, improved options.- Formalized LICENSE.- Defaults to closing socket after sending close_notify, fixes hanging.problem that would occur sometime when waiting for other party'sclose_notify.- Update SRP to RFC 5054 compliance.- Removed client handshake "callbacks", no longer support the SRPre-handshake idiom within a single handshake function.- Bugfixes- Added hashlib support, removes Deprecation Warning due to sha and md5.- Handled GeneratorExit exceptions that are a new Python feature, andinterfere with the async code if not handled.- Removed:- Shared keys (it was based on an ancient I-D, not TLS-PSK).- cryptlib support, it wasn't used much, we have enough other options.- cryptoIDs (TACK is better).- win32prng extension module, as os.urandom is now available.- Twisted integration (unused?, slowed down loading).- Jython code (ancient, didn't work).- Compat support for python versions < 2.7.- Additions- Support for TACK via TACKpy.- Support for CertificateRequest.certificate_authorities ("reqCAs")- Added TLSConnection.shutdown() to better mimic socket.- Enabled Session resumption for XMLRPCTransport.0.3.8 - 2/21/2005- Added support for poplib, imaplib, and smtplib- Added python 2.4 windows installer- Fixed occassional timing problems with test suite0.3.7 - 10/05/2004- Added support for Python 2.2- Cleaned up compatibility code, and docs, a bit0.3.6 - 9/28/2004- Fixed script installation on UNIX- Give better error message on old Python versions0.3.5 - 9/16/2004- TLS 1.1 support- os.urandom() support- Fixed win32prng on some systems0.3.4 - 9/12/2004- Updated for TLS/SRP draft 8- Bugfix: was setting _versioncheck on SRP 1st hello, causing problemswith GnuTLS (which was offering TLS 1.1)- Removed _versioncheck checking, since it could cause interop problems- Minor bugfix: when cryptlib_py and and cryptoIDlib present, cryptlibwas complaining about being initialized twice0.3.3 - 6/10/2004- Updated for TLS/SRP draft 7- Updated test cryptoID cert chains for cryptoIDlib 0.3.10.3.2 - 5/21/2004- fixed bug when handling multiple handshake messages per record (e.g. IIS)0.3.1 - 4/21/2004- added xmlrpclib integration- fixed hanging bug in Twisted integration- fixed win32prng to work on a wider range of win32 sytems- fixed import problem with cryptoIDlib- fixed port allocation problem when test scripts are run on some UNIXes- made tolerant of buggy IE sending wrong version in premaster secret0.3.0 - 3/20/2004- added API docs thanks to epydoc- added X.509 path validation via cryptlib- much cleaning/tweaking/re-factoring/minor fixes0.2.7 - 3/12/2004- changed Twisted error handling to use connectionLost()- added ignoreAbruptClose0.2.6 - 3/11/2004- added Twisted errorHandler- added TLSAbruptCloseError- added 'integration' subdirectory0.2.5 - 3/10/2004- improved asynchronous support a bit- added first-draft of Twisted support0.2.4 - 3/5/2004- cleaned up asyncore support- added proof-of-concept for Twisted0.2.3 - 3/4/2004- added pycrypto RSA support- added asyncore support0.2.2 - 3/1/2004- added GMPY support- added pycrypto support- added support for PEM-encoded private keys, in pure python0.2.1 - 2/23/2004- improved PRNG use (cryptlib, or /dev/random, or CryptoAPI)- added RSA blinding, to avoid timing attacks- don't install local copy of M2Crypto, too problematic0.2.0 - 2/19/2004- changed VerifierDB to take per-user parameters- renamed tls_lite -> tlslite0.1.9 - 2/16/2004- added post-handshake 'Checker'- made compatible with Python 2.2- made more forgiving of abrupt closure, since everyone does it:if the socket is closed while sending/recv'ing close_notify,just ignore it.0.1.8 - 2/12/2004- TLSConnections now emulate sockets, including makefile()- HTTPTLSConnection and TLSMixIn simplified as a result0.1.7 - 2/11/2004- fixed httplib.HTTPTLSConnection with multiple requests- fixed SocketServer to handle close_notify- changed handshakeClientNoAuth() to ignore CertificateRequests- changed handshakeClient() to ignore non-resumable session arguments0.1.6 - 2/10/2004- fixed httplib support0.1.5 - 2/09/2004- added support for httplib and SocketServer- added support for SSLv3- added support for 3DES- cleaned up read()/write() behavior- improved HMAC speed0.1.4 - 2/06/2004- fixed dumb bug in tls.py0.1.3 - 2/05/2004- change read() to only return requested number of bytes- added support for shared-key and in-memory databases- added support for PEM-encoded X.509 certificates- added support for SSLv2 ClientHello- fixed shutdown/re-handshaking behavior- cleaned up handling of missing_srp_username- renamed readString()/writeString() -> read()/write()- added documentation0.1.2 - 2/04/2004- added clienttest/servertest functions- improved OpenSSL cipher wrappers speed- fixed server when it has a key, but client selects plain SRP- fixed server to postpone errors until it has read client's messages- fixed ServerHello to only include extension data if necessary0.1.1 - 2/02/2004- fixed close_notify behavior- fixed handling of empty application data packets- fixed socket reads to not consume extra bytes- added testing functions to tls.py0.1.0 - 2/01/2004- first release