tls-parser

2.0.2 verified Mon Apr 27 auth: no python

tls-parser is a small library to parse TLS records. Current version 2.0.2 supports Python >=3.8. It provides classes like TlsRecord, TlsHandshake, and parsing of TLS 1.2 and 1.3. The library appears to be in maintenance mode with infrequent releases.

pip install tls-parser

Common errors

error ModuleNotFoundError: No module named 'tls_parser' ↓

cause The package is installed as 'tls-parser' but the import expects the hyphenated name.

fix

Install the package with 'pip install tls-parser' and use 'import tls_parser' (the internal module uses underscores).

error AttributeError: module 'tls_parser' has no attribute 'TlsRecord' ↓

cause TlsRecord is not exposed at the top-level package. It's in a submodule.

fix

Use 'from tls_parser.tls_record import TlsRecord' instead.

error tls_parser.exceptions.TlsParserException: Cannot parse record: incomplete data ↓

cause The input bytes are shorter than the record length specified in the header.

fix

Ensure the complete TLS record is provided, including all payload bytes as per the length field.

Warnings

breaking In version 2.0.0, the package name changed from 'tls_parser' to 'tls-parser' on PyPI, and the top-level module name changed accordingly. Old imports from 'tls_parser' may still work if the package is installed, but code relying on the old module layout may break. ↓

fix Use 'pip install tls-parser' and update imports to match current module structure (e.g., from tls_parser.tls_record import TlsRecord).

gotcha The library expects raw bytes of a full TLS record (including the 5-byte header). If you pass an incomplete record or omit the header, parsing will fail or produce incorrect results. ↓

fix Ensure the input bytes include the TLS record header (content type, version, length) and the correct number of payload bytes as specified in the length field.

deprecated The package has not been updated since 2021 and may not support recent TLS extensions or newer Python versions beyond 3.8. ↓

fix Consider using alternatives like 'pycryptodome' or 'scapy' for TLS parsing if you need ongoing support.

Imports

TlsRecord
wrong
```
from tls_parser import TlsRecord
```
correct
```
from tls_parser.tls_record import TlsRecord
```
TlsRecord is not in the top-level __init__.py; must import from the specific module.
TlsHandshake
wrong
```
from tls_parser import TlsHandshake
```
correct
```
from tls_parser.tls_handshake import TlsHandshake
```
TlsHandshake is in the tls_handshake module, not directly under tls_parser.

Quickstart

Parses a raw TLS record from bytes and prints the record type and TLS version.

from tls_parser.tls_record import TlsRecord
from tls_parser.tls_version import TlsVersionEnum

# Parse a TLS record from raw bytes (example: TLS 1.2 handshake)
raw_bytes = bytes.fromhex('16030300a2' + '00' * 162)  # Minimal handshake
record = TlsRecord.from_bytes(raw_bytes)
print('Record type:', record.record_type)
print('TLS version:', TlsVersionEnum(record.tls_version).name)