Install & Compatibility
Where this runs
tested against v0.9.0b2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.604s · 21.4MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 1.9s · import 0.532s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TLSConnection
✓ from tlslite.api import TLSConnection
✗ from tlslite import TLSConnection
`TLSConnection` and other core classes are exposed via the `tlslite.api` module.
HandshakeSettings
✓ from tlslite.api import HandshakeSettings
✗ from tlslite.handshakesettings import HandshakeSettings
While `HandshakeSettings` exists in its own module, the recommended way is to import from `tlslite.api` for consistency.
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()
Debug
Known issues
deprecatedStarting 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.fixRun your test suite with `-Wd` to identify deprecated calls. Update your code to use the snake_case equivalents (e.g., `handshakeClient` -> `handshake_client`).
affects: >=0.8.0
breakingVersion 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.fixEnsure 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.
affects: >=0.8.0, <0.9.0b2
gotchaNew 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.fixTo 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.
affects: <0.9.0b1
Errors
Common errors & fixes
DeprecationWarning: Call to deprecated function (e.g., handshakeClient): Use handshake_client instead.
Using `camelCase` method names that have been deprecated since version 0.8.0.
fixUpdate method calls to `underscore_separator` (snake_case) style. For example, change `connection.handshakeClient(...)` to `connection.handshake_client(...)`.
ImportError: No module named 'tlslite.api'
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).
fixEnsure `tlslite-ng` is correctly installed: `pip install tlslite-ng`. Verify your import statement: `from tlslite.api import ...`.
tlslite.errors.TLSError: AlertDescription.protocol_version
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.
fixReview 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`).
Upgrade
Version history
0.8.2latest on PyPI · released Jan 22, 2025
Audit
Dependencies
No dependency data recorded yet.