crypto/tls: handshake aborts with opaque "invalid argument" when KeyLogWriter is a typed-nil *os.File

[raiftekin]

Go version

go version go1.26.0 darwin/arm64

Output of go env in your module/workspace:

AR='ar'
CC='clang'
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_ENABLED='1'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
CXX='clang++'
GCCGO='gccgo'
GO111MODULE=''
GOARCH='arm64'
GOARM64='v8.0'
GOAUTH='netrc'
GOBIN=''
GOCACHE='/Users/raif/Library/Caches/go-build'
GOCACHEPROG=''
GODEBUG=''
GOENV='/Users/raif/Library/Application Support/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOGCCFLAGS='-fPIC -arch arm64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -ffile-prefix-map=/var/folders/.../T/go-build=/tmp/go-build -gno-record-gcc-switches -fno-common'
GOHOSTARCH='arm64'
GOHOSTOS='darwin'
GOINSECURE=''
GOMOD='/tmp/keylog-repro/go.mod'
GOMODCACHE='/Users/raif/go/pkg/mod'
GONOPROXY=''
GONOSUMDB=''
GOOS='darwin'
GOPATH='/Users/raif/go'
GOPRIVATE=''
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/Users/raif/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.26.0.darwin-arm64'
GOSUMDB='sum.golang.org'
GOTELEMETRY='local'
GOTELEMETRYDIR='/Users/raif/Library/Application Support/go/telemetry'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/Users/raif/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.26.0.darwin-arm64/pkg/tool/darwin_arm64'
GOVCS=''
GOVERSION='go1.26.0'
GOWORK=''
PKG_CONFIG='pkg-config'

What did you do?

A common pattern for debug-only TLS key logging is a helper that returns *os.File and nil when debug is off. Plugging that helper's return value directly into tls.Config.KeyLogWriter (an io.Writer) makes the interface non-nil with a nil concrete value, and the handshake fails.

The Playground cannot reach the network, so reproduction is local:

package main

import (
	"crypto/tls"
	"fmt"
	"net/http"
	"os"
)

var debug = false

// Returns the key-log file when debug is on, nil otherwise.
func getKeyLogWriter() *os.File {
	if !debug {
		return nil
	}
	f, _ := os.OpenFile("/tmp/keys.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
	return f
}

func main() {
	client := &http.Client{
		Transport: &http.Transport{
			TLSClientConfig: &tls.Config{
				KeyLogWriter: getKeyLogWriter(), // typed-nil *os.File → non-nil io.Writer
			},
		},
	}

	resp, err := client.Get("https://example.com/")
	if err != nil {
		fmt.Printf("ERROR: %v\n", err)
		return
	}
	defer resp.Body.Close()
	fmt.Printf("OK: status=%d\n", resp.StatusCode)
}

Because Go boxes a typed-nil *os.File into a non-nil interface, the c.KeyLogWriter == nil check inside crypto/tls does not detect the value as nil, and writeKeyLog proceeds to call Write on the nil *os.File, which returns os.ErrInvalid.

What did you see happen?

ERROR: Get "https://example.com/": invalid argument

The TLS handshake aborts. The error gives no indication that KeyLogWriter is involved — the user has to bisect their tls.Config to find it. With either a real keylog file or KeyLogWriter: nil, the same code works.

What did you expect to see?

Either:

1. The handshake succeeds (write errors from KeyLogWriter are non-fatal, since the field is documented as a debug aid), or
2. The returned error makes clear that KeyLogWriter is the source so the user can fix their config without bisecting.

At minimum, the failure shouldn't be a bare invalid argument propagated from (*os.File).Write on a nil receiver.

[gabyhelp]

Related Issues

• import/path: An error occurred in tls.Config.KeyLogWriter, causing the tls handshake to fail abnormally. #74358 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[mwriter]

Because Go boxes a typed-nil *os.File into a non-nil interface, the c.KeyLogWriter == nil check inside crypto/tls does not detect the value as nil, and writeKeyLog proceeds to call Write on the nil *os.File, which returns os.ErrInvalid.

This is an old problem:
#24635
And this year, by the way, there was a similar issue:
#77733
In general, there are specific solutions to this issue, but in this case you hardly have a choice but to write strict code:

func getKeyLogWriter() io.Writer {
	if !debug {
		return nil
	}
	f, _ := os.OpenFile("/tmp/keys.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
	return f
}

or

func getKeyLogWriter() *os.File { ... }

var w io.Writer
if debug {
	w = getKeyLogWriter()
}
client := &http.Client{
	Transport: &http.Transport{
		TLSClientConfig: &tls.Config{
				KeyLogWriter: w,
		},
	},
}

[JunyangShao]

@golang/security

[gopherbot]

Change https://go.dev/cl/784740 mentions this issue: crypto/tls: wrap KeyLogWriter errors w/ prefix

[cpu]

Hi @raiftekin, thanks for the detailed report.

I think this is a pretty classic instance of a typed-nil interface footgun. I don't think the tls package should try to detect this case (e.g. using reflect), and instead there are two straight-forward ways to avoid the pitfall in your calling code:

A) Change getKeyLogWriter to return io.Writer instead of *os.File.
B) Keep the *os.File return, but change the callsite to something like:

  cfg := &tls.Config{}
  if w := getKeyLogWriter(); w != nil {
      cfg.KeyLogWriter = w
  }

What did you expect to see?
Either:

The handshake succeeds (write errors from KeyLogWriter are non-fatal, since the field is documented as a debug aid), or
The returned error makes clear that KeyLogWriter is the source so the user can fix their config without bisecting.

I agree that the debugging experience you encountered makes it hard to know the KeyLogWriter impl was the culprit and was probably frustrating.

I don't think making the write errors silently ignored is a great option, but I do think we can make the source of the error clearer. PTAL at CL 784740 where I've proposed such a change.