uTLS Documentation

Dict TLS is a vendored version of godicttls. It provides a dictionary for TLS written in Go, offering bidirectional mapping between TLS parameter/extension values and their corresponding names. It also includes enum convenience for working with these values.

The data used in this dictionary is sourced from IANA assignments for:

• Transport Layer Security (TLS) Parameters
• Transport Layer Security (TLS) Extensions

The UConn type extends the standard tls.Conn. It is the primary interface for managing a connection with custom TLS configurations. It maintains a slice of TLSExtension objects and a public ClientHandshakeState.

When UConn.BuildHandshakeState() is called (either manually or automatically during UConn.Handshake()), the configuration is applied based on the selected ClientHelloID:

• HelloGolang: Uses the default Go makeClientHello() implementation. uTLS-specific customizations are ignored.
• Other ClientHelloIDs: Populates UConn.Hello.{Random, CipherSuites, CompressionMethods} and UConn.Extensions based on a 'parrot' setup. These are then applied to standard TLS structs and marshaled into HandshakeState.Hello.

uTLS bypasses the limitations of Go's crypto/tls package (where many handshake structs and fields are private) by using public copies of private structs.

To manipulate the handshake, you can modify the fields of the public ClientHandshakeState. Before the handshake begins, uTLS performs a shallow copy of your public state into the internal Go clientHandshakeState, executes the handshake, and then copies the resulting state back to your public struct so you can inspect the handshake results.

uTLS can mimic the ClientHello of popular browsers (like Chrome and Firefox).

Important Caveats:

• We must offer ciphersuites and TLS extensions that are not supported by standard crypto/tls. This is safe if you control the server and can disable these unsupported features.
• Parroting is imperfect and only covers the ClientHello phase.
• For certain browsers like iOS, you should call utls.EnableWeakCiphers() prior to use to avoid connection breakage.

Refer to the compatibility table in the documentation for specific fingerprint IDs and unsupported extensions for each browser version.

You can use raw bytes from a captured ClientHello to generate a ClientHelloSpec that mimics the original client's properties. This is useful for making new connections look like they originate from the same software as the captured traffic.

Steps:

1. Create a Fingerprinter and use FingerprintClientHello on the raw bytes (the bytes must include the full TLS record: type, version, and length).
2. Create a UClient using tls.HelloCustom.
3. Apply the generated spec using uConn.ApplyPreset(generatedSpec).

uConn := UClient(&net.TCPConn{}, nil, HelloCustom)
fingerprinter := &Fingerprinter{}
generatedSpec, err := fingerprinter.FingerprintClientHello(rawCapturedClientHelloBytes)
if err != nil {
  panic("fingerprinting failed: %v", err)
}
if err := uConn.ApplyPreset(generatedSpec); err != nil {
  panic("applying generated spec failed: %v", err)
}

You can construct a custom handshake by following these steps:

1. Call tls.UClient() with tls.HelloCustom to obtain an empty configuration.
2. Populate the UConn.Hello fields (e.g., Random, CipherSuites, CompressionMethods) if necessary.
3. Configure and add TLS Extensions to UConn.Extensions. Extensions are marshaled in the order they are added.
4. Set Session and SessionCache as required.

Warning: If you need to manually control all raw bytes on the wire, you can set UConn.HandshakeStateBuilt = true and marshal the clientHello into UConn.HandshakeState.Hello.raw yourself. If you do this, you are responsible for ensuring the Config and ClientHelloMsg match your manual setup to avoid confusing the underlying crypto/tls implementation.

To replace the standard Go crypto/tls with uTLS, follow these steps:

1. Import the library using an alias to avoid conflicts with the standard library: import tls "github.com/refraction-networking/utls".
2. Select a clientHelloID (e.g., utls.HelloChrome_Auto).
3. Replace the standard tls.Client call with tls.UClient.

Standard crypto/tls usage:

config := tls.Config{ServerName: "www.google.com"}
tlsConn := tls.Client(dialConn, &config)

uTLS usage:

config := tls.Config{ServerName: "www.google.com"}
// Use tls.UClient instead of tls.Client
tlsConn := tls.UClient(dialConn, &config, utls.HelloChrome_Auto)

A UConn is a specialized TLS connection that allows for fingerprinting resistance and custom handshakes. The behavior of the connection is heavily influenced by the ClientHelloID passed during initialization via UClient:

• HelloGolang: Uses the default Go TLS ClientHello structure.
• Mimicking IDs: Uses a predefined ClientHello structure to mimic other browsers or clients.
• HelloCustom: Allows for a completely custom ClientHello by manually configuring the Extensions slice on the UConn object.

UConn automatically calls BuildHandshakeState before performing the handshake to ensure the ClientHello is correctly marshaled based on your configuration.

uTLS provides pre-defined ClientHelloSpec configurations (often referred to as 'parrots') that mimic the TLS handshake characteristics of specific browsers and operating systems (e.g., Firefox, iOS, Edge, Safari). Using these specs helps a client resist fingerprinting by presenting a ClientHello that looks like a legitimate, common browser.

Each spec defines:

• TLSVersMin and TLSVersMax: The supported TLS version range.
• CipherSuites: The list of supported cipher suites.
• CompressionMethods: Supported compression algorithms.
• Extensions: A list of TLSExtension objects that define the specific handshake extensions (like SNIExtension, KeyShareExtension, SupportedCurvesExtension, etc.) used by that specific client version.