tls-client

To use TLS-Client in Go, you initialize a CookieJar, define HttpClientOptions (such as timeouts, client profiles, and redirect settings), and then create the client using tls_client.NewHttpClient. You can then use the client to perform standard HTTP operations like Do, Get, Post, or Head using requests from the github.com/bogdanfinn/fhttp package.

package main

import (
	"fmt"
	"io"
	"log"

	http "github.com/bogdanfinn/fhttp"
	ls_client "github.com/bogdanfinn/tls-client"
	"github.com/bogdanfinn/tls-client/profiles"
)

func main() {
	jar := tls_client.NewCookieJar()
	options := []tls_client.HttpClientOption{
		tls_client.WithTimeoutSeconds(30),
		tls_client.WithClientProfile(profiles.Chrome_144),
		tls_client.WithNotFollowRedirects(),
		tls_client.WithCookieJar(jar), // create cookieJar instance and pass it as argument
	}

	client, err := tls_client.NewHttpClient(tls_client.NewNoopLogger(), options...)
	if err != nil {
		log.Println(err)
		return
	}

	req, err := http.NewRequest(http.MethodGet, "https://tls.peet.ws/api/all", nil)
	if err != nil {
		log.Println(err)
		return
	}

	req.Header = http.Header{
		"accept":                    {"*/*"},
		"accept-language":           {"de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7"},
		"user-agent":                {"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36"},
		http.HeaderOrderKey: {
			"accept",
			"accept-language",
			"user-agent",
		},
	}

	resp, err := client.Do(req)
	if err != nil {
		log.Println(err)
		return
	}

	defer resp.Body.Close()

	log.Println(fmt.Sprintf("status code: %d", resp.StatusCode))

	readBytes, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Println(err)
		return
	}

	log.Println(string(readBytes))
}

To bypass TLS fingerprinting, you must match a target client's TLS handshake characteristics. This library provides a way to translate a standard JA3 string into a tls.ClientHelloSpec used by the utls engine.

The Process

1. JA3 String Parsing: The JA3 string is split into components: Ciphers, Extensions, Curves, and Point Formats.
2. Parameter Mapping: Since a JA3 string often only contains IDs, you must provide additional context (like supportedSignatureAlgorithms or supportedVersions) to fully reconstruct the ClientHelloSpec required for a valid handshake.
3. Extension Construction: The factory maps the parsed IDs and your provided parameters into specific tls.TLSExtension implementations (e.g., tls.SignatureAlgorithmsExtension, tls.KeyShareExtension, tls.ALPNExtension).
4. Spec Generation: The resulting ClientHelloSpec contains the CipherSuites, Extensions, and GetSessionID function needed to impersonate the target client.

The HttpClient interface extends the standard Go net/http client with specialized methods for cookie management, proxy configuration, and fingerprinting-related access. It is the primary interface used to interact with the library.

type HttpClient interface {
    GetCookies(u *url.URL) []*http.Cookie
    SetCookies(u *url.URL, cookies []*http.Cookie)
    SetCookieJar(jar http.CookieJar)
    GetCookieJar() http.CookieJar
    SetProxy(proxyUrl string) error
    GetProxy() string
    SetFollowRedirect(followRedirect bool)
    GetFollowRedirect() bool
    CloseIdleConnections()
    Do(req *http.Request) (*http.Response, error)
    Get(url string) (resp *http.Response, err error)
    Head(url string) (resp *http.Response, err error)
    Post(url, contentType string, body io.Reader) (resp *http.Response, err error)

    GetBandwidthTracker() bandwidth.BandwidthTracker
    GetDialer() proxy.ContextDialer
    GetTLSDialer() TLSDialerFunc
}

The TLSClientRequestPayload object defines the parameters for an HTTP request. It allows for fine-grained control over TLS fingerprinting, proxy settings, and HTTP behavior.

Key configuration options:

• requestUrl: The target URL.
• requestMethod: One of 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'.
• requestBody: The string representation of the request body.
• requestCookies: An optional array of cookie objects [{ [key: string]: string }].
• tlsClientIdentifier: An optional identifier for a pre-defined TLS fingerprint (e.g., 'chrome_103').
• followRedirects: Boolean to control redirect behavior.
• insecureSkipVerify: Boolean to skip TLS certificate verification.
• isByteResponse: Boolean to indicate if the response should be treated as bytes.
• withoutCookieJar: Boolean to bypass the internal cookie jar.
• withRandomTLSExtensionOrder: Boolean to randomize TLS extension order.
• timeoutSeconds: Number of seconds before the request times out.
• sessionId: The ID of an existing session to reuse.
• proxyUrl: The proxy URL to use for the request.
• headers: An object containing custom HTTP headers { [key: string]: string }.
• headerOrder: An array of strings defining the order of headers.
• customTlsClient: An object for providing a manual, highly specific TLS configuration (JA3, H2 settings, etc.).

The client provides fine-grained control over the TLS handshake and network layer:

• WithClientProfile(clientProfile profiles.ClientProfile): Sets the TLS fingerprint/profile (e.g., Chrome, Firefox).
• WithRandomTLSExtensionOrder(): Randomizes the order of TLS extensions in the ClientHello.
• WithInsecureSkipVerify(): Skips SSL certificate verification.
• WithCertificatePinning(certificatePins map[string][]string, handlerFunc BadPinHandlerFunc): Enables SSL Pinning. certificatePins is a map where the key is the host and the value is a slice of valid pins. handlerFunc is called if a bad pin is detected.
• WithServerNameOverwrite(serverName string): Overwrites the server name used for certificate verification and ClientHello (requires WithInsecureSkipVerify to work properly).
• WithForceHttp1(): Forces the client to use HTTP/1.1.
• WithDisableHttp3(): Disables HTTP/3 (falls back to HTTP/2).
• WithProtocolRacing(): Races HTTP/3 (QUIC) and HTTP/2 (TCP) connections simultaneously, using the one that connects first.
• WithDisableIPV4() / WithDisableIPV6(): Forces the connection to use only IPv6 or IPv4 respectively.