Add boringssl support to the ja4_fingerprint plugin #12790

jasmine-nahrain · 2026-01-08T00:52:01Z

Problem
OpenSSL provides SSL_client_hello_get0_ext(), SSL_client_hello_get0_ciphers() and SSL_client_hello_get1_extensions_present() to get client hello from an SSL object. BoringSSL doesn't have comparable functions. It requires the SSL_CLIENT_HELLO object via SSL_early_callback_ctx_extension_get(). Currently, there's no way to get the SSL_CLIENT_HELLO object in plugins, which causes friction when writing SSL-related plugins that need to work with both libraries.

Proposed Solution:

TSClientHello TSVConnClientHelloGet(TSVConn sslp);

This API provides access to the SSL_CLIENT_HELLO object within plugins and is usable during SSL hooks (TS_SSL_CLIENT_HELLO_HOOK, TS_SSL_SERVERNAME_HOOK).

Use Case: This enables plugins to access ClientHello data (cipher suites, extensions, SNI, ALPN, supported TLS versions) when using BoringSSL. Currently, the ja4_fingerprint plugin only works for openssl, this change allows us to add boringssl support.

Implementation Notes:

The SSL_CLIENT_HELLO is captured during the client hello callback and stored in TLSSNISupport
The data is valid during SSL handshake hooks
For OpenSSL, plugins can continue using existing TSSslConnectionGet() approach

This is a non-breaking addition. Existing OpenSSL-based plugins continue to work unchanged.

jasmine-nahrain · 2026-01-21T03:13:36Z

[approve ci autest 1]

bneradt

Thank you @jasmine-nahrain for exploring this. I think your patch here makes the plugin code look much better. I'm content with this idea as a compromise that addresses our variety of wants here (minimize noise in the ts.h namespace along with a clean boring+openssl interface for the plugin).

@maskit : I'm curious to hear your opinion on this as well. Are you content with this patch?

plugins/experimental/ja4_fingerprint/plugin.cc

bneradt · 2026-01-23T23:58:25Z

include/ts/apidefs.h.in

+struct tsapi_ssl_client_hello {
+  uint16_t       version;
+  const uint8_t *cipher_suites;
+  size_t         cipher_suites_len;
+  const uint8_t *extensions;
+  size_t         extensions_len;
+  int           *extension_ids;
+  size_t         extension_ids_len;
+  void          *ssl_ptr;
+};


Let's initialize these here (nullptr, 0).

Also: as a tweak on this, what do you think of making these private and adding public getters for these such that we can lazily load them as they are requested? Subsequent requests can then return the populated (cached) values if the same value is asked for twice. Currently, the caller has to pay for the population of all of these even though they might not need them all.

Lazy load would be tricky. Best we can do is probably read and cache everything in TSVConnClientHelloGet.

As I commented on somewhere, SSL_CLIENT_HELLO is only available during BoringSSL callback functions are called. So TSVConnClientHelloGet needs to be called on certain hooks (this should be documented). This plugin seems fine since TSVConnClientHelloGet and TSClientHelloDestroy are called on TS_SSL_CLIENT_HELLO_HOOK, but if another plugin needs information from Client Hello later on another hook, everything needs to be deep copied when TSVConnClientHelloGet is called.

Public getters would be nice even if we don't do lazy land. Those would enable removing ifdef from the plugin code.

maskit

API documentation is mandatory.

The structure should probably be a class with public getters (and private members). Regardless, some of member variables should have const.

maskit · 2026-01-28T19:14:49Z

plugins/experimental/ja4_fingerprint/plugin.cc

-  if (ch->extensions != nullptr) {
-    const uint8_t *ext       = ch->extensions;
-    size_t         remaining = ch->extensions_len;
+  // For BoringSSL, we have direct access to the extensions buffer


Can't ch have a function that returns an iterator for extension type IDs so plugins don't need to deal with the difference?

for (auto ext_type : ch->get_extension_types()) { summary.add_extension(ext_type); }

bneradt

Looking good. As @maskit said, we'll need doc/ documentation for this too.

include/ts/apidefs.h.in

bneradt

lgtm

maskit · 2026-01-29T17:10:12Z

doc/developer-guide/api/types/TSClientHello.en.rst

+Description
+===========
+
+:type:`TSClientHello` is an opaque handle to a TLS ClientHello message sent by


It's not just a handle. I think the accessors need to be listed. Otherwise reading the header file would be the only way to know how to use it.

maskit · 2026-01-29T17:56:54Z

include/ts/apidefs.h.in

+
+  // Returns a vector of extension type IDs
+  // This abstracts the difference between BoringSSL (extensions buffer) and OpenSSL (extension_ids array)
+  std::vector<uint16_t>


Hmm, I was expecting a custom iterable object. This implementation copies each item (extension type) into a vector. A custom iterator that internally manages an index/offset would avoid the copy.

Maybe we can hide the actual type, which is currently std:vector, by typedef/using for now, and tell that this function returns an iterable object. Then we can replace/optimize the implementation later. It would be nice if we could declare it like Iterable interface in Java, but I'm not sure how to do it in C++.

maskit · 2026-01-29T18:07:58Z

doc/developer-guide/api/functions/TSVConnClientHelloGet.en.rst

+===========
+
+:func:`TSVConnClientHelloGet` retrieves ClientHello message data from the TLS
+virtual connection :arg:`sslp`. This function is typically called from the


Since we don't deep copy the information, we can use this function only on limited hooks. I'm sure we can use TS_EVENT_SSL_CLIENT_HELLO, but I'm not sure if it's the only hook or there are other hooks.

The documentation should list up all the hooks, or tell that TS_EVENT_SSL_CLIENT_HELLO is the only hook supported (maybe for now, until somebody confirms another hook work as well).

jasmine-nahrain added 8 commits January 6, 2026 15:56

got client hello routed to plugins

786fbaa

Creates ja4 fingerprint with boringssl

3f4e5c4

cleanup a bit

5c8c8ed

make ssl_client_hello const

0efeade

spaces cleanup

9765eb8

cleanup code

2bc38d0

more cleanup

fd03806

Update plugin.cc

9b76bd0

jasmine-nahrain self-assigned this Jan 8, 2026

jasmine-nahrain added the Plugins label Jan 8, 2026

masaori335 added the ja4_fingerprint Work related to JA4 fingerprinting label Jan 8, 2026

masaori335 added this to the 10.2.0 milestone Jan 8, 2026

jasmine-nahrain added 3 commits January 8, 2026 12:07

Update plugin.cc

51ebe55

Update ts.h

b57f338

Update apidefs.h.in

162af78

bryancall requested a review from bneradt January 12, 2026 22:55

Update to make more clean

a42ae48

bneradt requested changes Jan 24, 2026

View reviewed changes

maskit requested changes Jan 24, 2026

View reviewed changes

Update data

19bbc06

jasmine-nahrain requested review from bneradt and maskit January 28, 2026 03:20

maskit reviewed Jan 28, 2026

View reviewed changes

bneradt requested changes Jan 28, 2026

View reviewed changes

include/ts/apidefs.h.in Outdated Show resolved Hide resolved

address comments

4dc5af8

jasmine-nahrain requested review from bneradt and maskit January 29, 2026 00:28

jasmine-nahrain added 2 commits January 29, 2026 11:40

Update ja4_fingerprint.en.rst

4a51fac

Add docs

b2868d9

jasmine-nahrain added 2 commits January 29, 2026 14:19

Update TSVConnClientHelloGet.en.rst

b9e1351

Update TSVConnClientHelloGet.en.rst

3019dd7

bneradt approved these changes Jan 29, 2026

View reviewed changes

maskit reviewed Jan 29, 2026

View reviewed changes

Add boringssl support to the ja4_fingerprint plugin #12790

Are you sure you want to change the base?

Add boringssl support to the ja4_fingerprint plugin #12790

Conversation

jasmine-nahrain commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jasmine-nahrain commented Jan 21, 2026

Uh oh!

bneradt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bneradt Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

maskit Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maskit Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

maskit left a comment

Choose a reason for hiding this comment

Uh oh!

maskit Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

bneradt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bneradt left a comment

Choose a reason for hiding this comment

Uh oh!

maskit Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

maskit Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

maskit Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jasmine-nahrain commented Jan 8, 2026 •

edited

Loading

maskit Jan 24, 2026 •

edited

Loading

maskit Jan 29, 2026 •

edited

Loading