tlslite version 0.4.9 Aug 11 2015 Trevor Perrin <tlslite at trevp.net> http://trevp.net/tlslite/

Table of Contents

1 Introduction 2 License/Acknowledgements 3 Installation 4 Getting Started with the Command-Line Tools 5 Getting Started with the Library 6 Using TLS Lite with httplib 7 Using TLS Lite with poplib or imaplib 8 Using TLS Lite with smtplib 9 Using TLS Lite with SocketServer 10 Using TLS Lite with asyncore 11 SECURITY CONSIDERATIONS 12 History

1 Introduction

TLS Lite is an open source python library that implements SSL and TLS. TLS Lite supports RSA and SRP ciphersuites. TLS Lite is pure python, however it can use other libraries for faster crypto operations. TLS Lite integrates with several stdlib neworking libraries.

API documentation is available in the 'docs' directory.

If you have questions or feedback, feel free to contact me. For discussing improvements to tlslite, also see 'tlslite-dev@googlegroups.com'.

2 Licenses/Acknowledgements

TLS Lite is written (mostly) by Trevor Perrin. It includes code from Bram Cohen, Google, Kees Bos, Sam Rushing, Dimitris Moraitis, Marcelo Fernandez, Martin von Loewis, Dave Baggett, Yngve N. Pettersen (ported by Paul Sokolovsky), Mirko Dziadzka, David Benjamin, and Hubert Kario.

All code in TLS Lite has either been dedicated to the public domain by its authors, or placed under a BSD-style license. See the LICENSE file for details.

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 fast RSA operations and fast ciphers.

• If you have pycrypto this will be used for fast RSA operations and fast ciphers.

• If you have the GMPY interface to GMP, this will be used for fast RSA and SRP operations.

• These modules don't need to be present at installation - you can install them 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 testing other TLS implementations, or as example code. Note that 'tls.py server' runs an HTTPS server which will serve files rooted at the current directory by default, so be careful.

'tlsdb.py' lets you manage SRP verifier databases. These databases are used by a 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:4443

Try connecting to the server with a web browser, or with:

tls.py client localhost:4443

X.509 with TACK

To run an X.509 server using a TACK, install TACKpy, then run the same server command as above with added arguments:

... -t TACK1.pem localhost:4443

SRP

To run an SRP server, try something like:

tlsdb.py createsrp verifierDB tlsdb.py add verifierDB alice abra123cadabra 1024 tlsdb.py add verifierDB bob swordfish 2048

tls.py server -v verifierDB localhost:4443

Then try connecting to the server with:

tls.py client localhost:4443 alice abra123cadabra

HTTPS

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 the sections 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 TLSConnection

Or 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 site like Amazon, which doesn't require client authentication, but which will authenticate itself using an X.509 certificate chain.

The ClientCert function can also be used to do client authentication with an X.509 certificate chain and corresponding private key. To use X.509 chains, you'll need some way of creating these, such as OpenSSL (see http://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, parsePEMKey s = 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 - see RFC 5054 for details.

If you want more control over the handshake, you can pass in a HandshakeSettings instance. For example, if you're performing SRP, but you only want to use SRP parameters of at least 2048 bits, and you only want to use 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 = 2048 settings.cipherNames = ["aes256"] settings.minVersion = (3,1) settings.useExperimentalTACKExtension = True # Needed for TACK support

connection.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, TACK support will be enabled by default, but for now it is an experimental feature which relies on a temporary TLS Extension number, and should not be used for production software.) This will cause the client to request the server to send you a TACK (and/or any TACK Break Signatures):

Finally, every TLSConnection has a session object. You can try to resume a previous session by passing in the session object from the old session. If the server remembers this old session and supports resumption, the handshake will finish more quickly. Otherwise, the full handshake will be done. For example:

connection.handshakeClientSRP("alice", "abra123cadabra") . . oldSession = connection.session connection2.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 it several different parameters, depending on which types of authentication you're willing to perform.

To perform SRP authentication, you have to pass in a database of password verifiers. The VerifierDB class manages an in-memory or on-disk verifier database.

verifierDB = VerifierDB("./test/verifierDB") verifierDB.open() connection.handshakeServer(verifierDB=verifierDB)

To perform authentication with a certificate and private key, the server must load these as described in the previous section, then pass them in. If the server sets the reqCert boolean to True, a certificate chain will be requested from 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 last section, for finer control over handshaking details.

If you are passing in a certificate chain+private key, you may additionally provide 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 support

connection.handshakeServer(certChain=certChain, privateKey=privateKey, tack=tack, settings=settings)

Finally, the server can maintain a SessionCache, which will allow clients to use session resumption:

sessionCache = SessionCache() connection.handshakeServer(verifierDB=verifierDB, sessionCache=sessionCache)

It should be noted that the session cache, and the verifier databases, are all thread-safe.

5 Step 4 - check the results

If the handshake completes without raising an exception, authentication results will be stored in the connection's session object. The following variables w