pyca / pyca/pyopenssl

Add support for set_client_hello_callback to expose TLS ClientHello in Python to enable JA3 TLS fingerprinting

Open
#1,430 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
944
Forks
440
Avg merge
1d 6h
Merged PRs (30d)
6

Description

Hello!

While working on GlobaLeaks we are evaluating performing TLS fingerprinting (e.g., JA3) during ALPN negotiation.

This is modern and common practice to being able to identify bots and ddos.

OpenSSL 1.1.1 and newer provide the SSL_CTX_set_client_hello_cb function, which allows registering a callback to receive the raw ClientHello during handshake.

Currently, PyOpenSSL does not expose this function or its related APIs, making it impossible to use this important OpenSSL feature from Python.

With this ticket i would like to propose exporting SSL_CTX_set_client_hello_cb and any related structures or functions needed to use this callback from Python, ideally via the existing SSL.Context interface.

This would allow Python projects to implement TLS ClientHello inspection cleanly and efficiently without requiring native patches or external dependencies.

Exposing this function would unlock powerful use cases such as:

  • Passive TLS fingerprinting (JA3 hashing)
  • Early protocol negotiation (ALPN)
  • Custom TLS handshake behaviors based on ClientHello content

Thank you very much for considering this. I’m happy to assist with testing or provide examples if helpful.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the existing SSL.Context interface and the OpenSSL 1.1.1 SSL_CTX_set_client_hello_cb API described in the issue. Determine which related callback structures or functions are required for Python access, then verify that a Python project can inspect ClientHello data during the handshake for fingerprinting or ALPN use.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.