tls

Documentation

Overview

Package tls provides TLS connection utilities with browser fingerprint spoofing. It wraps the utls library to create TLS connections that mimic real browser TLS handshakes, including cipher suites, extensions, and other fingerprint elements.

Index

• Constants
• func BuildChrome143Spec(serverName string) *utls.ClientHelloSpec
• func BuildFirefox146Spec(serverName string) *utls.ClientHelloSpec
• func BuildSafari261Spec(serverName string) *utls.ClientHelloSpec
• func GenerateGREASEBytes(length int) []byte
• func IsGREASE(v uint16) bool
• func RandomGREASE() uint16
• func RandomGREASEPair() (uint16, uint16)
• func RandomUint32() uint32
• type BrowserType
• type Dialer
  • func Chrome143Dialer() *Dialer
  • func Firefox146Dialer() *Dialer
  • func NewCustomDialer(p *profile.BrowserProfile) *Dialer
  • func NewDialer(p *profile.BrowserProfile) *Dialer
  • func NewDialerWithProxy(p *profile.BrowserProfile, proxy *ProxyConfig) *Dialer
  • func Safari261Dialer() *Dialer
  • func (d *Dialer) Dial(network, addr string) (*utls.UConn, error)
  • func (d *Dialer) DialContext(ctx context.Context, network, addr string) (*utls.UConn, error)
  • func (d *Dialer) DialQUIC(ctx context.Context, addr string) (*quic.Conn, error)
  • func (d *Dialer) SetDNSCache(cache *dns.Cache)
  • func (d *Dialer) SetKeepAlive(keepAlive time.Duration)
  • func (d *Dialer) SetTimeout(timeout time.Duration)
• type ProxyConfig
  • func ParseProxy(s string, proxyType ProxyType) (*ProxyConfig, error)
  • func (p *ProxyConfig) Addr() string
  • func (p *ProxyConfig) Dial(ctx context.Context, network, addr string) (net.Conn, error)
• type ProxyType
• type SpecBuilder
  • func NewSpecBuilder(p *profile.BrowserProfile) *SpecBuilder
  • func (b *SpecBuilder) Build(serverName string) *utls.ClientHelloSpec
  • func (b *SpecBuilder) WithShuffleExtensions(shuffle bool) *SpecBuilder

Constants

const TCP_FASTOPEN_CONNECT = 30 // Linux 4.11+

TCP_FASTOPEN_CONNECT is the socket option for client-side TFO on Linux. This allows sending data in the SYN packet, eliminating 1 RTT.

Functions

func BuildChrome143Spec

func BuildChrome143Spec(serverName string) *utls.ClientHelloSpec

BuildChrome143Spec builds a Chrome 143 ClientHelloSpec for the given server.

func BuildFirefox146Spec

func BuildFirefox146Spec(serverName string) *utls.ClientHelloSpec

BuildFirefox146Spec builds a Firefox 146 ClientHelloSpec for the given server.

func BuildSafari261Spec

func BuildSafari261Spec(serverName string) *utls.ClientHelloSpec

BuildSafari261Spec builds a Safari 26.1 ClientHelloSpec for the given server.

func GenerateGREASEBytes

func GenerateGREASEBytes(length int) []byte

GenerateGREASEBytes generates random bytes for GREASE extension data.

func IsGREASE

func IsGREASE(v uint16) bool

IsGREASE checks if the given value is a GREASE value.

func RandomGREASE

func RandomGREASE() uint16

RandomGREASE returns a random GREASE value.

func RandomGREASEPair

func RandomGREASEPair() (uint16, uint16)

RandomGREASEPair returns two different random GREASE values.

func RandomUint32

func RandomUint32() uint32

RandomUint32 returns a random uint32 for session ID or other purposes.

Types

type BrowserType

type BrowserType int

BrowserType identifies the browser family for fingerprint generation.

const (
	BrowserChrome BrowserType = iota
	BrowserFirefox
	BrowserSafari
)

type Dialer

type Dialer struct {

	// UseBuiltinChrome uses uTLS built-in Chrome preset instead of custom spec.
	// This is more reliable but gives less control over the exact fingerprint.
	UseBuiltinChrome bool
	// InsecureSkipVerify skips TLS certificate verification.
	// WARNING: This should only be used for testing.
	InsecureSkipVerify bool
	// ForceHTTP1 forces HTTP/1.1 by only advertising http/1.1 in ALPN.
	ForceHTTP1 bool
	// contains filtered or unexported fields
}

Dialer creates uTLS connections with browser fingerprint spoofing.

func Chrome143Dialer

func Chrome143Dialer() *Dialer

Chrome143Dialer returns a dialer configured for Chrome 143. Uses built-in Chrome preset by default for reliability.

func Firefox146Dialer

func Firefox146Dialer() *Dialer

Firefox146Dialer returns a dialer configured for Firefox 146.

func NewCustomDialer

func NewCustomDialer(p *profile.BrowserProfile) *Dialer

NewCustomDialer creates a TLS dialer that uses a custom ClientHelloSpec. This gives more control but may be less compatible with some servers.

func NewDialer

func NewDialer(p *profile.BrowserProfile) *Dialer

NewDialer creates a new TLS dialer with the given profile. Uses custom ClientHelloSpec by default for maximum fingerprint control.

func NewDialerWithProxy

func NewDialerWithProxy(p *profile.BrowserProfile, proxy *ProxyConfig) *Dialer

NewDialerWithProxy creates a new TLS dialer with the given profile and proxy.

func Safari261Dialer

func Safari261Dialer() *Dialer

Safari261Dialer returns a dialer configured for Safari 26.1.

func (*Dialer) Dial

func (d *Dialer) Dial(network, addr string) (*utls.UConn, error)

Dial establishes a TLS connection with the configured fingerprint.

func (*Dialer) DialContext

func (d *Dialer) DialContext(ctx context.Context, network, addr string) (*utls.UConn, error)

DialContext establishes a TLS connection with the configured fingerprint.

func (*Dialer) DialQUIC

func (d *Dialer) DialQUIC(ctx context.Context, addr string) (*quic.Conn, error)

DialQUIC establishes a QUIC connection with browser-like transport parameters. The connection can be used to create an HTTP/3 transport. Note: TLS fingerprinting within QUIC uses standard crypto/tls. QUIC transport parameters are configured from the browser profile's HTTP3Profile.

func (*Dialer) SetDNSCache

func (d *Dialer) SetDNSCache(cache *dns.Cache)

SetDNSCache enables DNS caching with the given cache. This reduces DNS lookup latency for repeated requests to the same hosts.

func (*Dialer) SetKeepAlive

func (d *Dialer) SetKeepAlive(keepAlive time.Duration)

SetKeepAlive sets the TCP keep-alive period.

func (*Dialer) SetTimeout

func (d *Dialer) SetTimeout(timeout time.Duration)

SetTimeout sets the dial timeout.

type ProxyConfig

type ProxyConfig struct {
	Type     ProxyType
	Host     string
	Port     string
	Username string // empty for IP-authenticated proxies
	Password string
}

ProxyConfig holds proxy connection settings.

func ParseProxy

func ParseProxy(s string, proxyType ProxyType) (*ProxyConfig, error)

ParseProxy parses a proxy string in "host:port:user:pass" or "host:port" format.

func (*ProxyConfig) Addr

func (p *ProxyConfig) Addr() string

Addr returns the proxy address as host:port.

func (*ProxyConfig) Dial

func (p *ProxyConfig) Dial(ctx context.Context, network, addr string) (net.Conn, error)

Dial establishes a connection through the proxy to the target address.

type ProxyType

type ProxyType int

ProxyType indicates the proxy protocol.

const (
	ProxyTypeNone ProxyType = iota
	ProxyTypeHTTP
	ProxyTypeSOCKS5
)

type SpecBuilder

type SpecBuilder struct {
	// contains filtered or unexported fields
}

SpecBuilder builds uTLS ClientHelloSpec from a BrowserProfile.

func NewSpecBuilder

func NewSpecBuilder(p *profile.BrowserProfile) *SpecBuilder

NewSpecBuilder creates a new SpecBuilder for the given profile. By default, extensions are shuffled to mimic Chrome's behavior.

func (*SpecBuilder) Build

func (b *SpecBuilder) Build(serverName string) *utls.ClientHelloSpec

Build creates a ClientHelloSpec for the given server name.

func (*SpecBuilder) WithShuffleExtensions

func (b *SpecBuilder) WithShuffleExtensions(shuffle bool) *SpecBuilder

WithShuffleExtensions sets whether to shuffle extension order. Chrome randomizes extension order, so enabling this (default) produces more realistic fingerprints.