Chapter 1: Making private things public
There are numerous handshake-related structs in crypto/tls, most of which are either private or have private fields.
One of them — clientHandshakeState — has private function handshake(),
which is called in the beginning of default handshake.
Unfortunately, user will not be able to directly access this struct outside of tls package.
As a result, we decided to employ following workaround: declare public copies of private structs.
Now user is free to manipulate fields of public ClientHandshakeState.
Then, right before handshake, we can shallow-copy public state into private clientHandshakeState,
call handshake() on it and carry on with default Golang handshake process.
After handshake is done we shallow-copy private state back to public, allowing user to read results of handshake.
Chapter 2: TLSExtension
The way we achieve reasonable flexibilty with extensions is inspired by
ztls' design.
However, our design has several differences, so we wrote it from scratch.
This design allows us to have an array of TLSExtension objects and then marshal them in order:
type TLSExtension interface {
writeToUConn(*UConn) error
Len() int // includes header
// Read reads up to len(p) bytes into p.
// It returns the number of bytes read (0 <= n <= len(p)) and any error encountered.
Read(p []byte) (n int, err error) // implements io.Reader
}writeToUConn() applies appropriate per-extension changes to UConn.
Len() provides the size of marshaled extension, so we can allocate appropriate buffer beforehand,
catch out-of-bound errors easily and guide size-dependent extensions such as padding.
Read(buffer []byte) writes(see: io.Reader interface) marshaled extensions into provided buffer.
This avoids extra allocations.
Chapter 3: UConn
UConn extends standard tls.Conn. Most notably, it stores slice with TLSExtensions and public
ClientHandshakeState.
Whenever UConn.BuildHandshakeState() gets called (happens automatically in UConn.Handshake()
or could be called manually), config will be applied according to chosen ClientHelloID.
From contributor's view there are 2 main behaviors:
HelloGolangsimply calls default Golang'smakeClientHello()and directly stores it intoHandshakeState.Hello. utls-specific stuff is ignored.- Other ClientHelloIDs fill
UConn.Hello.{Random, CipherSuites, CompressionMethods}andUConn.Extensionswith per-parrot setup, which then gets applied to appropriate standard tls structs, and then marshaled by utls intoHandshakeState.Hello.
Tests exist, but coverage is very limited. What's covered is a conjunction of
- TLS 1.2
- Working parrots without any unsupported extensions (only Android 5.1 at this time)
- Ciphersuites offered by parrot.
- Ciphersuites supported by Golang
- Simple conversation with reference implementation of OpenSSL. (e.g. no automatic checks for renegotiations, parroting quality and such)
plus we test some other minor things. Basically, current tests aim to provide a sanity check.
Merge the src/crypto/tls subtree from an exact Go release tag. The recent
Go 1.23.4 (cefe226), Go 1.24.0 (a99feac), and Go 1.26.0 (ec54fa8)
updates are two-parent merges whose second parent is the upstream TLS subtree.
Preserve that history so Git can identify the upstream merge base on the next
update; do not squash the merge or replace it with a directory copy.
Start with a clean uTLS working tree on an update branch. For example:
# Add this remote once, if it does not already exist.
git remote add golang https://github.com/golang/go.git
git fetch --no-tags golang tag go1.27.1
git switch -c codex/update-go1.27.1
git subtree split --prefix=src/crypto/tls refs/tags/go1.27.1 \
--branch golang-tls-go1.27.1
git merge --no-ff --no-commit golang-tls-go1.27.1Use the release tag, not the moving Go development or release branch. Keep the upstream history available for the split, and inspect the previous sync merges before resolving conflicts. Record the Go tag and split commit in the update's description.
During the merge:
- Preserve the uTLS-specific behavior marked by
[uTLS]comments. Review the resulting code even where Git merges it cleanly. Propagate relevant upstream changes into duplicated paths such asu_handshake_client.goandu_quic.go, and check the public/private conversions inu_public.go. - Audit dependencies outside
src/crypto/tls, especially the localinternal/packages, against the same Go release. The subtree merge does not update these copies. Prefer exported standard-library APIs where available, and preserve the local adaptations for inaccessible Go internal packages. - uTLS does not implement Go's internal
godebugmachinery. Retain this limitation when porting upstream defaults and tests; environment-dependent TLS compatibility tests cannot assume the standard library's switches work here. Distinguish those switches from ones honored by imported standard-library packages. Port useful test helpers instead of importing Go-only internal packages, and explain tests that cannot be carried over. - Follow upstream changes to private structs and functions that uTLS exposes. If those changes break a public uTLS field or method, document the old and new API and any direct migration. Do not reconstruct removed internal state or add compatibility machinery solely to preserve the old API.
- Update the minimum Go version in
go.modand the toolchain used by.github/workflows/go.ymlwhen required by the imported code.
After resolving conflicts, format changed Go files and run:
go build ./...
go test ./...
go test -race ./...
git diff --checkPay particular attention to custom ClientHello handshakes, ECH (including the
inner transcript), HelloRetryRequest, PSK/session resumption and binder updates,
hybrid key shares, and public/private state conversions on failed handshakes.
Previous syncs needed follow-up fixes in these areas. Exercise both HelloGolang
and custom/parrot paths where applicable. Keep upstream test fixtures from the
same release, and report any unavailable platform or external-network checks.
Once validation is complete, commit the resolved merge with both parents intact.