I recently came across a TLS handshake issue when migrating a service from Go 1.21 to Go 1.24. The issue came up when consuming a vendor SOAP service that hasn’t changed in over 2 decades. I am writing this for my own documentation but as well as a reference if anyone else comes across this in the future.
Background
The specific error we were seeing in our integration suite was remote error: tls: handshake failure. These tests had completed normally in our UAT environment so it was at least isolated to this service along with the Go version changes. Additionally without any prior consent from the vendor, we were pretty confident what we were dealing with was self inflicted.
GODEBUG
A lot has changed in Go between 1.21 and 1.24. Upon searching for related context we came across the Go, Backwards Compatibility, and GODEBUG post by the Go team and found our culprit / solution. For those unaware, Go exposes a runtime environment variable GODEBUG which allows developers to enable features that are no longer supported due to insecure or buggy behavior.
In our specific case there were breaking changes in 1.22 and 1.23 that affected the minimum default supported TLS versions across the crypto package. As much as we would like to support the latest, the realities of a long running business are that we can’t control our vendors and sometimes shit happens like in this case when dealing with old services.
As of writing, here is a list of supported GODEBUG options in Go 1.24
The Fix
After debugging and testing a number of configuration options, we landed on adding the following to our applications entrypoint:
//go:debug tls10server=1
//go:debug tlsrsakex=1
//go:debug tls3des=1
package main
...
tls10server=1
In Go 1.23 the default TLS version is TLS 1.2 . By setting this flag it will default the server side to TLS 1.0
tlsrsakex=1 tls3des=1
These settings configure the default list of supported TLS Cipher Suites that Go will use when dealing with TLS 1.0 - 1.2 connections in applications. TLS Cipher Suites are a rabbit hole which refer to a lot of variables that account for whether or not a connection can be attained (certificates, networking, TLS compatibility, etc). In this particular case certain suites were removed in both Go 1.22 and 1.23 that we needed in our application, so we enabled these two suites to support those vendors.
Once the change was merged in our server was able to connect again and we resolved the issue.