Skip to content

Commit

Permalink
Change import path
Browse files Browse the repository at this point in the history
  • Loading branch information
mingyech committed Nov 12, 2024
1 parent 560e27c commit 590e2a3
Show file tree
Hide file tree
Showing 13 changed files with 35 additions and 34 deletions.
4 changes: 2 additions & 2 deletions .deepsource.toml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ test_patterns = ["**/*_test.go"]
name = "go"

[analyzers.meta]
import_root = "github.com/gaukas/clienthellod"
import_root = "github.com/refraction-networking/clienthellod"

[[transformers]]
name = "gofumpt"
name = "gofumpt"
23 changes: 12 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,19 @@
# `clienthellod`: TLS ClientHello/QUIC Initial Packet reflection service
![Go Build Status](https://github.com/gaukas/clienthellod/actions/workflows/go.yml/badge.svg)
[![Go Report Card](https://goreportcard.com/badge/github.com/gaukas/clienthellod)](https://goreportcard.com/report/github.com/gaukas/clienthellod)

![Go Build Status](https://github.com/refraction-networking/clienthellod/actions/workflows/go.yml/badge.svg)
[![Go Report Card](https://goreportcard.com/badge/github.com/refraction-networking/clienthellod)](https://goreportcard.com/report/github.com/refraction-networking/clienthellod)
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fgaukas%2Fclienthellod.svg?type=shield&issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Fgaukas%2Fclienthellod?ref=badge_shield&issueType=license)
[![Go Doc](https://pkg.go.dev/badge/github.com/refraction-networking/water.svg)](https://pkg.go.dev/github.com/refraction-networking/water)

`clienthellod`, read as "client-hello-D", is a TLS ClientHello/QUIC Initial Packet reflection service. It can be used to parses TLS ClientHello messages and QUIC Initial Packets into human-readable and highly programmable formats such as JSON.
`clienthellod`, read as "client-hello-D", is a TLS ClientHello/QUIC Initial Packet reflection service. It can be used to parses TLS ClientHello messages and QUIC Initial Packets into human-readable and highly programmable formats such as JSON.

Is is a part of the TLS fingerprintability research project which spans [tlsfingerprint.io](https://tlsfingerprint.io) and [quic.tlsfingerprint.io](https://quic.tlsfingerprint.io). It parses the ClientHello messages sent by TLS clients and QUIC Client Initial Packets sent by QUIC clients and display the parsed information in a human-readable format with high programmability.
Is is a part of the TLS fingerprintability research project which spans [tlsfingerprint.io](https://tlsfingerprint.io) and [quic.tlsfingerprint.io](https://quic.tlsfingerprint.io). It parses the ClientHello messages sent by TLS clients and QUIC Client Initial Packets sent by QUIC clients and display the parsed information in a human-readable format with high programmability.

See [tlsfingerprint.io](https://tlsfingerprint.io) and [quic.tlsfingerprint.io](https://quic.tlsfingerprint.io) for more details about the project.

## Quick Start

`clienthellod` comes as a Go library, which can be used to parse both TLS and QUIC protocols.
`clienthellod` comes as a Go library, which can be used to parse both TLS and QUIC protocols.

### TLS/QUIC Fingerprinter

Expand Down Expand Up @@ -65,7 +66,7 @@ See [tlsfingerprint.io](https://tlsfingerprint.io) and [quic.tlsfingerprint.io](
if err != nil {
panic(err)
}

// err := ch.ParseClientHello() // no need to call again, UnmarshalClientHello automatically calls ParseClientHello
```

Expand All @@ -85,7 +86,7 @@ See [tlsfingerprint.io](https://tlsfingerprint.io) and [quic.tlsfingerprint.io](

ci, err := clienthellod.UnmarshalQUICClientInitialPacket(buf[:n]) // decodes QUIC Client Initial Packet
if err != nil {
panic(err)
panic(err)
}

jsonB, err = json.MarshalIndent(cip, "", " ")
Expand All @@ -102,7 +103,7 @@ Implementations including Chrome/Chromium sends oversized Client Hello which doe

```go
gci := GatherClientInitials() // Each GatherClientInitials reassembles one QUIC Client Initial Packets stream. Use a QUIC Fingerprinter for multiple potential senders, which automatically demultiplexes the packets based on the source address.

udpConn, err := net.ListenUDP("udp", ":443")
defer udpConn.Close()

Expand All @@ -119,7 +120,7 @@ Implementations including Chrome/Chromium sends oversized Client Hello which doe

ci, err := clienthellod.UnmarshalQUICClientInitialPacket(buf[:n]) // decodes QUIC Client Initial Packet
if err != nil {
panic(err)
panic(err)
}

err = gci.AddPacket(ci)
Expand All @@ -131,10 +132,10 @@ Implementations including Chrome/Chromium sends oversized Client Hello which doe

### Use with Caddy

We also provide clienthellod as a Caddy Module in `modcaddy`, which you can use with Caddy to capture ClientHello messages and QUIC Client Initial Packets. See [modcaddy](https://github.com/gaukas/clienthellod/tree/master/modcaddy) for more details.
We also provide clienthellod as a Caddy Module in `modcaddy`, which you can use with Caddy to capture ClientHello messages and QUIC Client Initial Packets. See [modcaddy](https://github.com/refraction-networking/clienthellod/tree/master/modcaddy) for more details.

## License

This project is developed and distributed under Apache-2.0 license.
This project is developed and distributed under Apache-2.0 license.

[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fgaukas%2Fclienthellod.svg?type=large&issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Fgaukas%2Fclienthellod?ref=badge_large&issueType=license)
4 changes: 2 additions & 2 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@

## Reporting a Vulnerability

Use the form [here](https://github.com/gaukas/clienthellod/security/advisories/new) to report a vulnerability privately to the developers of this project.
Use the form [here](https://github.com/refraction-networking/clienthellod/security/advisories/new) to report a vulnerability privately to the developers of this project.

For low-severity or other impractical vulnerabilities, you may feel free to open an issue to discuss it.
For low-severity or other impractical vulnerabilities, you may feel free to open an issue to discuss it.
2 changes: 1 addition & 1 deletion clienthello.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import (
"runtime"
"sort"

"github.com/gaukas/clienthellod/internal/utils"
"github.com/refraction-networking/clienthellod/internal/utils"
tls "github.com/refraction-networking/utls"
"github.com/refraction-networking/utls/dicttls"
"golang.org/x/crypto/cryptobyte"
Expand Down
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
module github.com/gaukas/clienthellod
module github.com/refraction-networking/clienthellod

go 1.21.0

Expand Down
20 changes: 10 additions & 10 deletions modcaddy/README.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,32 @@
# `clienthellod/modcaddy`: clienthellod as a Caddy module


`clienthellod` is also provided as a Caddy plugin, `modcaddy`, which can be used to capture ClientHello messages and QUIC Client Initial Packets. See Section [modcaddy](#modcaddy) for more details.

`modcaddy` contains a Caddy plugin that provides:
- An caddy `app` that can be used to temporarily store captured ClientHello messages and QUIC Client Initial Packets.
- A caddy `handler` that can be used to serve the ClientHello messages and QUIC Client Initial Packets to the client sending the request.

- An caddy `app` that can be used to temporarily store captured ClientHello messages and QUIC Client Initial Packets.
- A caddy `handler` that can be used to serve the ClientHello messages and QUIC Client Initial Packets to the client sending the request.
- A caddy `listener` that can be used to capture ClientHello messages and QUIC Client Initial Packets.

You will need to use [xcaddy](https://github.com/caddyserver/xcaddy) to rebuild Caddy with `modcaddy` included.

It is worth noting that some web browsers may not choose to switch to QUIC protocol in localhost environment, which may result in the QUIC Client Initial Packet not being sent and therefore not being captured/analyzed.

## Build
## Build

```bash
xcaddy build --with github.com/gaukas/clienthellod/modcaddy
xcaddy build --with github.com/refraction-networking/clienthellod/modcaddy
```

### When build locally with changes
### When build locally with changes

```bash
xcaddy build --with github.com/gaukas/clienthellod/modcaddy --with github.com/gaukas/clienthellod/=./
xcaddy build --with github.com/refraction-networking/clienthellod/modcaddy --with github.com/refraction-networking/clienthellod/=./
```

## sample Caddyfile

A sample Caddyfile is provided in this directory.
A sample Caddyfile is provided in this directory.

## Known issues

Expand All @@ -38,12 +38,12 @@ There is no trivial solution to this issue, as there seems to be no way to force

### QUIC fingerprint missing for the first request

It is possible that a client sends both H2-over-TCP (TLS) and H3-over-UDP (QUIC) for the first time requesting a web page and decide to render the response from H2-over-TCP (TLS). In this case, the QUIC Client Initial Packet might be not yet recorded.
It is possible that a client sends both H2-over-TCP (TLS) and H3-over-UDP (QUIC) for the first time requesting a web page and decide to render the response from H2-over-TCP (TLS). In this case, the QUIC Client Initial Packet might be not yet recorded.

Reloading the page might help by fetching the cached QUIC fingerprint if it is captured and not yet expired.

### Fingerprint gone after reloading/refreshing the web page

Some web browsers may decide to reuse the existing unclosed connection for new HTTP requests instead of establishing a new one by sending a new TLS Client Hello or QUIC Initial Packet(s). In which case, no new fingerprint will be captured and if the old fingerprint is expired or otherwise removed, the fingerprint will be gone and nothing will be displayed.

Forcing the web browser to establish a new connection by closing the existing connection, opening a new tab, or use different domain names every time might help.
Forcing the web browser to establish a new connection by closing the existing connection, opening a new tab, or use different domain names every time might help.
2 changes: 1 addition & 1 deletion quic_client_initial_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import (
"testing"
"time"

. "github.com/gaukas/clienthellod"
. "github.com/refraction-networking/clienthellod"
)

var mapGatheredClientInitials = map[string][][]byte{
Expand Down
2 changes: 1 addition & 1 deletion quic_clienthello_reconstructor_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import (

crand "crypto/rand"

. "github.com/gaukas/clienthellod"
. "github.com/refraction-networking/clienthellod"
)

var (
Expand Down
2 changes: 1 addition & 1 deletion quic_clienthello_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import (

"golang.org/x/exp/slices"

. "github.com/gaukas/clienthellod"
. "github.com/refraction-networking/clienthellod"
)

func TestParseQUICClientHello(t *testing.T) {
Expand Down
2 changes: 1 addition & 1 deletion quic_common_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import (

_ "embed"

. "github.com/gaukas/clienthellod"
. "github.com/refraction-networking/clienthellod"
)

var mapValueToVLI = map[uint64][]byte{
Expand Down
2 changes: 1 addition & 1 deletion quic_crypto_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import (
"encoding/hex"
"testing"

. "github.com/gaukas/clienthellod"
. "github.com/refraction-networking/clienthellod"
)

func TestClientInitialKeysCalc(t *testing.T) {
Expand Down
2 changes: 1 addition & 1 deletion quic_frame_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import (
"math/rand"
"testing"

. "github.com/gaukas/clienthellod"
. "github.com/refraction-networking/clienthellod"
)

func TestPADDING(t *testing.T) {
Expand Down
2 changes: 1 addition & 1 deletion quic_transport_parameters_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import (
"reflect"
"testing"

. "github.com/gaukas/clienthellod"
. "github.com/refraction-networking/clienthellod"

"github.com/refraction-networking/utls/dicttls"
)
Expand Down

0 comments on commit 590e2a3

Please sign in to comment.