tlslite-ng

0.8.2 · active · verified Thu Apr 16

tlslite-ng is a pure Python implementation of SSL and TLS protocols, supporting modern standards like TLS 1.3 and various cryptographic algorithms. It aims to provide a flexible and robust solution for secure communication without relying on OpenSSL bindings. The current stable version is 0.8.2, with beta versions (0.9.x) introducing new features.

Common errors

```
DeprecationWarning: Call to deprecated function (e.g., handshakeClient): Use handshake_client instead.
```
cause Using `camelCase` method names that have been deprecated since version 0.8.0.

fix Update method calls to `underscore_separator` (snake_case) style. For example, change `connection.handshakeClient(...)` to `connection.handshake_client(...)`.
```
ImportError: No module named 'tlslite.api'
```
cause The `tlslite-ng` package is either not installed, or you are trying to import from an incorrect path (e.g., `tlslite` instead of `tlslite-ng` if you have an older, conflicting package).

fix Ensure `tlslite-ng` is correctly installed: `pip install tlslite-ng`. Verify your import statement: `from tlslite.api import ...`.
```
tlslite.errors.TLSError: AlertDescription.protocol_version
```
cause The client and server could not agree on a mutually supported TLS protocol version. This can happen if one side is too old or configured to use only specific versions not supported by the other.

fix Review the `minVersion` and `maxVersion` in your `HandshakeSettings`. Ensure the versions you specify are supported by the server you are connecting to, and that your `tlslite-ng` library version supports those protocols (e.g., TLS 1.3 requires newer `tlslite-ng`).

Warnings

deprecated Starting with tlslite-ng 0.8.0, `camelCase` method and argument names are deprecated in favor of `underscore_separator` (snake_case) naming conventions. New code should use snake_case, and deprecation warnings will be emitted for camelCase usage.
Fix: Run your test suite with `-Wd` to identify deprecated calls. Update your code to use the snake_case equivalents (e.g., `handshakeClient` -> `handshake_client`).
breaking Version 0.8.0 removed support for Python 3.2, 3.3, 3.4, and 3.5. Users on these Python versions must either remain on `tlslite-ng <0.8.0` or upgrade their Python interpreter.
Fix: Ensure your Python environment is 2.6, 2.7, or >=3.6. For Python 3.6+, consider upgrading to `tlslite-ng>=0.9.0b2` for restored 3.6 support.
gotcha New features like Delegated Credentials and ML-DSA certificates, as well as restored Python 3.6 support, are available in the 0.9.0b1/b2 beta releases. They are not present in the current stable 0.8.x series.
Fix: To utilize the latest features, install a beta version (e.g., `pip install tlslite-ng==0.9.0b2`). Be aware that beta versions may be less stable and intended for testing.

Install

pip install tlslite-ng Install stable version
pip install tlslite-ng==0.9.0b2 Install latest beta (e.g., for Python 3.6+ or new features)

Imports

TLSConnection
wrong:
```
from tlslite import TLSConnection
```
correct:
```
from tlslite.api import TLSConnection
```
`TLSConnection` and other core classes are exposed via the `tlslite.api` module.
HandshakeSettings
wrong:
```
from tlslite.handshakesettings import HandshakeSettings
```
correct:
```
from tlslite.api import HandshakeSettings
```
While `HandshakeSettings` exists in its own module, the recommended way is to import from `tlslite.api` for consistency.

Quickstart

This quickstart demonstrates how to establish a TLS client connection to a public HTTPS server using `tlslite-ng`. It covers creating a socket, wrapping it with `TLSConnection`, performing the handshake with specific `HandshakeSettings`, and then sending/receiving application data. It also includes error handling and proper connection closure.

import socket
from tlslite.api import TLSConnection, HandshakeSettings

# Minimal TLS client example connecting to a public HTTPS server
HOST = 'www.google.com'
PORT = 443

def run_client():
    sock = None
    connection = None
    try:
        # 1. Create a standard socket
        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        sock.connect((HOST, PORT))
        print(f"Connected to {HOST}:{PORT}")

        # 2. Wrap the socket with TLSConnection
        connection = TLSConnection(sock)

        # 3. Perform the TLS handshake as a client
        settings = HandshakeSettings()
        settings.minVersion = (3, 3) # TLS 1.2
        settings.maxVersion = (3, 4) # TLS 1.3

        connection.handshakeClient(
            settings=settings,
            reqCert=True # Request server certificate
        )
        print(f"TLS handshake successful. Protocol: {connection.version_name}")

        # 4. Send and receive application data
        request = b"GET / HTTP/1.1\r\nHost: www.google.com\r\nConnection: close\r\n\r\n"
        connection.write(request)
        print("Sent HTTP GET request.")

        response = connection.read()
        print("Received data (first 200 bytes):")
        print(response[:200].decode(errors='ignore'))

    except Exception as e:
        print(f"TLS client failed: {e}")
    finally:
        if connection: # Closes both the TLS connection and underlying socket
            connection.close()
        elif sock:
            sock.close()

if __name__ == '__main__':
    run_client()

view raw JSON →