tlsx

tlsx is a fork of the crypto/tls package of the Go standard library, extended with TLS features that crypto/tls does not have. Industrial, utility and device-management protocols need these features.

Attribution. tlsx is a fork of the crypto/tls package of the Go project, Copyright The Go Authors, under the BSD-3-Clause licence. Google's patent grant is in PATENTS. Most of the code in this repository is Go's. tlsx is maintained independently. It is not part of the Go project and is not affiliated with Go or Google, and neither has reviewed or endorsed it. NOTICE says what is Go's and what is ours; PROVENANCE.md does so file by file.

go get github.com/cB-Sigma/tlsx

Requires Go 1.27.1 or later. The current upstream base is Go 1.27.1.

Go's crypto/tls is deliberately small. It implements modern TLS for the web very well, and leaves out features the web does not need. Many industrial, utility and IoT protocols do need them:

• Their standards require TLS features that crypto/tls lacks, for example IEC 62351-3 (DNP3, IEC 60870-5-104, IEC 61850) and oneM2M TS-0003.
• Their devices are too small or too numerous for certificates, so they use pre-shared keys or raw public keys.

The Go project does not plan them for crypto/tls; pre-shared-key support, for example, is the request golang/go#6379. So a Go program that talks to such devices has three choices: cgo and OpenSSL, a different language, or a fork.

tlsx is that fork, kept as close to Go as possible:

• It carries Go's own code and git history.
• Its changes are small, marked // tlsx and opt-in.
• It is merged with every Go release, so Go's security fixes arrive as Go's own commits.
• It is pure Go, with no cgo.

If crypto/tls already does what you need, use crypto/tls. It is maintained by the Go team and has a smaller surface. Some of tlsx's additions exist only because protocol standards demand them and weaken security when misused:

• the integrity-only and NULL suites give no confidentiality;
• static DH and renegotiation have known pitfalls. All of them are off unless you turn them on. Turn on only what your protocol requires.

If you need FIPS 140-3, use crypto/tls in FIPS mode, not tlsx.

• Go's FIPS 140-3 mode rests on the Go Cryptographic Module. The module is validated as it ships inside the standard library.
• A fork outside the standard library can't use its internal packages. tlsx calls the public crypto packages instead and carries its own copy of the TLS key derivation, so tlsx is not FIPS 140-3 validated.
• Several of tlsx's additions are not FIPS-approved algorithms anyway.
• GODEBUG settings work as in crypto/tls (see below), but tlsx reads them itself, so they do not change the FIPS 140-3 status either.

With a zero Config.Ext and the default cipher suites and groups, tlsx behaves like crypto/tls of its base Go release. Every addition is opt-in:

• Pre-shared keys.

  • TLS 1.2 PSK, DHE_PSK and ECDHE_PSK key exchanges (RFC 4279, RFC 5489) with the suites of RFC 5487, 6655, 7905 and 8442.
  • For old devices, the legacy HMAC-SHA-1 CBC suites of RFC 4279 and RFC 5489 (TLS_PSK_WITH_AES_128_CBC_SHA and the like), also in TLS 1.0 and 1.1.
  • TLS 1.2 PSK session resumption (PSKConfig.Resumption), by ticket or session ID, bound to the PSK: a removed or changed key ends it.
  • TLS 1.3 external PSKs (RFC 8446 4.2.11) with psk_dhe_ke and, optionally, psk_ke.
  • TLS 1.3 resumption of external-PSK sessions (PSKConfig.Resumption with TLS13; RFC 8446 2.2, 4.6.1), in both modes and bound to the PSK like TLS 1.2's. The client offers the ticket first and its external identity second, so a server that cannot resume the ticket still takes the PSK in the same round trip; not the external identity with ECH.
  • No certificate needed.

• Raw public keys (RFC 7250). TLS 1.2 and 1.3, both directions, trusted through a pinning callback.

• TLS 1.2 secure renegotiation (RFC 5746) in both roles, and TLS 1.2 resumption by session ID.

• TLS 1.3 KeyUpdate on demand (Conn.SendKeyUpdate), and a peer's timed KeyUpdates on idle links (Ext.MinKeyUpdateInterval, below).

• Extra cipher suites.

  • TLS_DHE_RSA_WITH_AES_128/256_GCM on the RFC 7919 groups.
  • ECDHE CBC-SHA384 (RFC 5289).
  • TLS_AES_128_CCM_SHA256 and TLS_AES_128_CCM_8_SHA256.
  • The integrity-only TLS 1.3 suites of RFC 9150. They provide no confidentiality.
  • TLS_RSA_WITH_NULL_SHA256.
  • Static DH TLS_DH_RSA_WITH_AES_128_GCM_SHA256.

• encrypt_then_mac (RFC 7366) for CBC suites.

• More groups.

  • ffdhe2048/3072/4096 (RFC 7919).
  • brainpoolP256r1/P384r1/P512r1 (RFC 7027, RFC 8734), with brainpool ECDSA certificates.

• More signature schemes. rsa_pss_pss_* and RSASSA-PSS CA keys.

• More extensions.

  • status_request_v2 (RFC 6961) and per-certificate OCSP in TLS 1.3.
  • trusted_ca_keys (RFC 6066).
  • certificate_authorities in the ClientHello.
  • max_fragment_length (RFC 6066).
  • The RFC 5878 authorization extensions, with RFC 4680 SupplementalData.

• SHA-1 signatures in TLS 1.2, off by default as in Go 1.25 and later: GODEBUG tlssha1=1 for the process, or Config.Ext.AllowSHA1Signatures for one Config (it can only allow; ConnectionState().Ext.SHA1Signature reports their use).

• GODEBUG. The settings crypto/tls reads (tlssha1, tlsmlkem, tlssecpmlkem, tlsmaxrsasize) come from the GODEBUG environment variable, else from the build's defaults (the go.mod go and godebug lines, //go:debug directives), else Go's defaults. tlsx reads them once, at first use: a later os.Setenv("GODEBUG", ...) is not seen, and runtime/metrics' /godebug/non-default-behavior/... counters are not fed; GODEBUGValue and GODEBUGNonDefault report the values and counts instead.

The package documentation (doc.go) has the details and the API.

Things tlsx does not do:

• FIPS 140-3 mode;
• 0-RTT (early data), as crypto/tls.

Example uses: IEC 62351-3 profiles for DNP3, IEC 60870-5-104 and IEC 61850 MMS; oneM2M TS-0003 pre-shared-key and raw-public-key security; wireless M-Bus / OMS gateways.

tlsx has the same API as crypto/tls. Change the import and set the fields of Config.Ext that you need:

import "github.com/cB-Sigma/tlsx"

// Client: TLS 1.3 with an external pre-shared key, no certificates.
cfg := &tlsx.Config{
	ServerName: "gateway.example",
	MinVersion: tlsx.VersionTLS13,
	Ext: tlsx.ConfigExt{PSK: &tlsx.PSKConfig{
		TLS13:    true,
		Identity: []byte("device-42"),
		Key:      key, // 32 bytes
	}},
}
conn, err := tlsx.Dial("tcp", "gateway.example:5684", cfg)

x_example_test.go has runnable examples for pre-shared keys and raw public keys.

tlsx's Config and Conn are distinct types from crypto/tls's. Code that takes a *tls.Config, such as net/http, needs an adapter, for example a net.Listener that returns tlsx connections.

Since Go 1.26.6, crypto/tls closes a connection after more than 16 post-handshake messages in a row with no application data, and a TLS 1.3 KeyUpdate no longer counts as data. This stops a peer from making the other side derive keys without end. It also drops a peer that renews its keys on a timer over a link that carries no data, as IEC 62351-3 devices on OpenSSL or mbedTLS may: the 17th renewal ends the connection.

Config.Ext.MinKeyUpdateInterval allows for such peers, and is off by default:

cfg.Ext.MinKeyUpdateInterval = renewal / 2 // the peer renews every `renewal`

• A KeyUpdate that arrives at least the interval after the last one that counted (or after the handshake) counts as progress, like data.
• Faster KeyUpdates count as in crypto/tls, so a flood is still cut off at the same limit. Key derivations stay bounded by one per interval plus 16.
• The count of ignored messages is not reset, only not increased; data still resets it as in crypto/tls.
• Time is taken from Config.Time when the record is read, so keep a reader on the connection. Choose the interval with a margin below the peer's period (half is a good default); a very short one gives back most of the protection.
• With zero, tlsx behaves exactly as crypto/tls; a test checks this against the toolchain's crypto/tls.

Neither crypto/tls nor tlsx checks whether a certificate was revoked; both leave it to the VerifyConnection hook. The package revocation is such a hook, for servers that authenticate client certificates (devices, gateways, operators) and for clients. It checks the peer's verified chains against certificate revocation lists (CRLs, RFC 5280), and works with crypto/tls as well as tlsx:

import "github.com/cB-Sigma/tlsx/revocation"

chk, err := revocation.New(revocation.Config{
	Sources: []revocation.Source{
		{Issuer: deviceCA, URL: "http://pki.example/device-ca.crl"},
		{Issuer: rootCA, File: "/etc/pki/root.crl"},
	},
})
if err != nil { ... }
defer chk.Close()

// crypto/tls
cfg := &tls.Config{
	ClientAuth:       tls.RequireAndVerifyClientCert,
	ClientCAs:        pool,
	VerifyConnection: chk.VerifyConnection,
}

// tlsx
xcfg := &tlsx.Config{
	ClientAuth: tlsx.RequireAndVerifyClientCert,
	ClientCAs:  pool,
	VerifyConnection: func(cs tlsx.ConnectionState) error {
		return chk.CheckChains(cs.VerifiedChains)
	},
}

VerifyPeerCertificate fits the hook of the same name in crypto/tls, tlsx and pion/dtls, and CheckChain checks a single chain.

• What is checked. The leaf and every intermediate, each against the CRL of its issuer. A CRL is used only if its issuer name matches the CA, its signature verifies with the CA's key, and it is within its thisUpdate and nextUpdate times. Every verified chain must pass.
• Failure policy. Fail-closed is the default for every CA that has a CRL configured: if the CRL is missing, unreadable, badly signed or past its nextUpdate, the certificate is refused with a clear error. Fail-open must be chosen per CA; it still refuses certificates listed in the last good CRL. A CA without a configured CRL is not checked, and Status lists it as "not configured".
• Refresh. CRLs come from files or HTTP(S) URLs. They are refetched periodically and ahead of nextUpdate, with back-off on failure. HTTP fetches have a timeout and a size limit. The last good CRL is kept, and a CRL with a lower CRL number is refused as a rollback.
• Status. Status reports, per CRL, the last fetch, thisUpdate, nextUpdate, CRL number, number of entries, last error and whether it is stale. Config.OnEvent feeds metrics or logs.
• Limits.
  • No OCSP yet; Config.Extra is the extension point for it.
  • No delta CRLs: a delta CRL is refused rather than taken for a full one.
  • No indirect CRLs and no CRLs partitioned by reason. CRLs partitioned by distribution point URI are supported.
  • Unknown critical CRL extensions make a CRL unusable.
  • The rollback check is in memory and does not survive a restart.

The package documentation (revocation/doc.go) has the details; revocation/example_test.go has the examples.

tlsx carries Go's files with small, marked changes, on top of Go's own history:

• The repository's history starts with every Go commit that touched the files tlsx carries, rewritten to tlsx's layout by git filter-repo and otherwise unchanged. git blame names the Go author and commit of each Go line; the ID map is in docs/upstream-commit-map.txt.
• The package rename and import rewrites are separate mechanical: commits, listed in .git-blame-ignore-revs. GitHub's blame view reads that file; locally, run git config blame.ignoreRevsFile .git-blame-ignore-revs once, and rewritten lines blame to the Go commits that wrote them.
• A new Go release comes in as a git merge of its filtered history (scripts/sync-upstream.sh), followed by a mechanical rewrite commit. Conflicts appear only where upstream changed lines that tlsx changed.
• A weekly GitHub workflow checks for a new stable Go release, runs the sync on a scratch branch and opens an issue with the result.
• Go's own crypto/tls tests run in this repository, apart from a documented list of skips.

UPSTREAM.md describes the procedure and each rewrite.

Security fixes in Go's crypto/tls reach tlsx only through a sync. If you depend on tlsx, follow its releases as you would follow Go's.

Features were checked against implementations other than Go where one exists. The interoperability tests run in CI (Ubuntu's OpenSSL and GnuTLS) and locally when the tools are installed; the table records the versions of the last local run.

Tested against another implementation:

Tested only by tlsx's own tests (Go client against Go server):

• status_request_v2 (RFC 6961, ocsp_multi). OpenSSL and GnuTLS don't implement it.
• trusted_ca_keys (RFC 6066 6). OpenSSL and GnuTLS don't implement it.
• RFC 5878 authorization extensions and SupplementalData. No maintained implementation is known.
• Static DH (TLS_DH_RSA_WITH_AES_128_GCM_SHA256). Current OpenSSL and GnuTLS don't support static DH suites.
• ffdhe3072/4096 and brainpoolP384r1/P512r1 in handshakes. Only ffdhe2048 and brainpoolP256r1 go through a handshake with OpenSSL. The curve arithmetic of all three brainpool curves is cross-checked with OpenSSL.
• ClientHelloInfo.Ext and the event observer.
• External PSK with Encrypted Client Hello. The identity is not sent.
• TLS 1.2 PSK session resumption (tickets and session IDs, refusal after a key is removed or changed); BoGo's PSK cipher-suite tests also resume against BoringSSL's runner.
• TLS 1.3 external-PSK resumption details: obfuscated ticket ages and binders of both identities, also after a HelloRetryRequest; ticket lifetime on both sides; the client dropping sessions of a changed key or identity; resumption inside Encrypted Client Hello; a server answering a psk_ke-only offer (OpenSSL's s_client always offers psk_dhe_ke too). BoGo has no TLS 1.3 external-PSK tests.
• GODEBUG sources and precedence (environment, build defaults), and tlssha1=1 end to end.
• The revocation package's refresh, HTTP source, failure policy and handshakes (crypto/tls and tlsx servers, TLS 1.2 and 1.3), with CRLs made by crypto/x509. Only CRL parsing is checked against OpenSSL.

Upstream behaviour. Go's own crypto/tls tests run here with small adjustments, listed in UPSTREAM.md:

• 5 tests skip at run time, each with its reason (go test -v): 2 that use the external network and 3 recorded renegotiation flights (tlsx's renegotiation ClientHello differs). The tests that set GODEBUG run, since tlsx honours GODEBUG. TestBogoSuite skips unless asked (below);
• the FIPS 140 variant in tls_test.go is replaced by a skip (no FIPS mode);
• tls_test.go sets Config.Ext in its Config.Clone test and leaves tlsx's extra cipher suites out of its checks of upstream's suite lists.

They include the handshakes recorded against OpenSSL in testdata/. They exercise the upstream code paths; they say nothing about tlsx's additions.

Not done.

• No independent security audit.
• No fuzzing beyond Go's own tests.

BoGo is BoringSSL's TLS conformance suite: a test runner, written in Go, that drives a "shim" through thousands of handshakes, including broken and hostile ones. tlsx carries Go's shim (bogo_shim_test.go, a copy of Go 1.27.1's, see UPSTREAM.md) and runs it with scripts/bogo.sh, weekly in CI (.github/workflows/bogo.yml) and on demand. BoringSSL is downloaded at the revision Go pins (v0.0.0-20260209204302-2a7ca5404e13) through the Go module proxy; nothing of it is in this repository.

Results on that revision (3562 tests; "skipped" are tests whose shim flags neither Go's shim nor tlsx's implement, and those Go's bogo_config.json disables):

• Differences from Go, and what they found. The first run of tlsx with Go's shim failed 7 tests that Go passes: tlsx used an RSASSA-PSS certificate key for RSA key exchange and for PKCS #1 v1.5, rsa_pss_rsae and TLS 1.0/1.1 signatures (CertificateCipherMismatch-PSS, RejectPSSKeyType-*). Fixed; since then every test Go passes, tlsx passes too.
• tlsx's flags (x_bogo_test.go) map BoGo's shim flags onto tlsx's features: -psk and -psk-identity (TLS 1.2 PSK suites, resumption), -renegotiate-freely, -renegotiate-once, -expect-total-renegotiations, -expect-secure-renegotiation, -expect-no-secure-renegotiation (client renegotiation), -key-update (sending KeyUpdate), -no-ticket (session-ID resumption) and the exporter flags the cipher-suite tests need. They bring 234 more tests into the run (229 pass, 5 are the expected failures below): the cipher-suite client and server tests of every version (114), PSK (67), renegotiation and HelloRequest (30), exporters (17), -no-ticket (4) and KeyUpdate (2). They found three more bugs, now fixed: a renegotiation could change the use of the extended master secret, a HelloRequest packed with the server's Finished stalled the client, and the legacy SHA-1 PSK suites, empty TLS 1.2 identities and PSK session resumption were missing.
• Expected failures (bogo_config_tlsx.json; they run, and one that starts to pass fails the test):
  • Renegotiate-Client, Renegotiate-Client-TLS12: the runner takes any session ID in a renegotiation ClientHello for an offer to resume; tlsx, like crypto/tls, always sends a random session ID and offers no session when renegotiating.
  • Renegotiate-Client-NoExt-Allowed: tlsx renegotiates only with peers that support secure renegotiation (RFC 5746).
  • Renegotiate-Client-Once-2: tlsx, like crypto/tls, refuses a second renegotiation with a warning-level no_renegotiation alert (RFC 5246 7.2.2); the runner ignores warnings and expects BoringSSL's fatal alert.
  • ExportKeyingMaterial-Server-HalfRTT-TLS-TLS13: 0-RTT is not implemented (nor in crypto/tls); Go's shim accepts -enable-early-data without acting on it.
• SHA-1. Go's bogo_config.json disables BoGo's 23 SHA-1 signature tests. Run with them enabled, Go and tlsx agree test by test: 19 fail and 4 pass by default, all 23 pass with GODEBUG tlssha1=1.
• MinKeyUpdateInterval. TLSX_BOGO_MIN_KEY_UPDATE_INTERVAL (not a BoGo flag) sets the option in the shim. With 1h every result is the same as without it, test by test; BoGo's flood test TooManyKeyUpdates still passes. With 1ns, which gives the protection back, that test fails, as it should.
• What BoGo cannot cover, because BoringSSL does not implement it: TLS 1.3 external PSKs, finite-field DHE (DHE_RSA, DHE_PSK), AES-CCM, raw public keys, max_fragment_length, encrypt_then_mac, brainpool, ffdhe groups, status_request_v2, trusted_ca_keys, the NULL and integrity-only suites, and server-side renegotiation (BoGo only checks that a server refuses it). -max-send-fragment has no tlsx counterpart (tlsx negotiates max_fragment_length instead). These rely on the interoperability tests above.

BSD-3-Clause, the same licence as Go's; see LICENSE, PATENTS and NOTICE. Contributions are accepted under the same licence (CONTRIBUTING.md). To report a vulnerability, see SECURITY.md.