crypto/tls: misleading "remote error: tls: certificate required" error when client cert CA not in server's accepted CAs list

[vinnie-v]

Go version

go version go1.24.6 linux/amd64

Output of go env in your module/workspace:

AR='ar'
CC='gcc'
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_ENABLED='1'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
CXX='g++'
GCCGO='gccgo'
GO111MODULE=''
GOAMD64='v1'
GOARCH='amd64'
GOAUTH='netrc'
GOBIN=''
GOCACHE='/home/ubuntu/.cache/go-build'
GOCACHEPROG=''
GODEBUG=''
GOENV='/home/ubuntu/.config/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOGCCFLAGS='-fPIC -m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -ffile-prefix-map=/tmp/go-build1329920774=/tmp/go-build -gno-record-gcc-switches'
GOHOSTARCH='amd64'
GOHOSTOS='linux'
GOINSECURE=''
GOMOD='/home/ubuntu/repos/go-mtls-ticket/go.mod'
GOMODCACHE='/home/ubuntu/go/pkg/mod'
GONOPROXY='bitbucket.org/REDACTED/*'
GONOSUMDB='bitbucket.org/REDACTED/*'
GOOS='linux'
GOPATH='/home/ubuntu/go'
GOPRIVATE='bitbucket.org/REDACTED/*'
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/usr/lib/go-1.24'
GOSUMDB='sum.golang.org'
GOTELEMETRY='local'
GOTELEMETRYDIR='/home/ubuntu/.config/go/telemetry'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/usr/lib/go-1.24/pkg/tool/linux_amd64'
GOVCS=''
GOVERSION='go1.24.6'
GOWORK=''
PKG_CONFIG='pkg-config'

What did you do?

package main

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

func main() {
	clientCert, err := tls.LoadX509KeyPair("certificate", "key")
	if err != nil {
		log.Fatalf("Failed to load client certificate: %v", err)
	}

	tlsConfig := &tls.Config{
		Certificates: []tls.Certificate{clientCert},
		ServerName:   "localhost",
	}
	client := &http.Client{
		Transport: &http.Transport{
			TLSClientConfig: tlsConfig,
		},
	}
	resp, err := client.Get("https://localhost:8443/")
	if err != nil {
		log.Printf("TLS Error: %v", err)
		return
	}

	fmt.Printf("%v\n", resp.Status)
}

Example HAProxy configuration:

global
    daemon

defaults
    mode http
    timeout connect 5000ms
    timeout client 50000ms
    timeout server 50000ms

frontend mtls_frontend
    # Client certificate CA not present (remote error: tls: certificate required)
    bind *:8443 ssl crt /etc/ssl/certs/haproxy-server.pem verify required ca-file /etc/ssl/certs/USERTrust_RSA_Certification_Authority.pem
    # Client certificate CA present (success)
    #bind *:8443 ssl crt /etc/ssl/certs/haproxy-server.pem verify required ca-file /etc/ssl/certs/chain.pem
    default_backend web_servers

backend web_servers
    server web1 [127.0.0.1:8080](http://127.0.0.1:8080/) check

What did you see happen?

The crypto/tls library will not configure the client certificate if the signing certificate authority is not present in the list provided by the server in CertificateRequest. The current implementation causes the remote error: tls: certificate required error making debugging the underlying CA issue difficult.

What did you expect to see?

An error explaining the certificate is not in the list of trusted CAs provided by the server. This behaviour does not occur for mTLS with TLS v1.2. I raised this previously in the golang-nuts group:

https://groups.google.com/g/golang-nuts/c/Cyn1uulURkg

[gabyhelp]

Related Issues

• crypto/tls: RequireAndVerifyClientCert is not working as intended. #63122 (closed)
• crypto/tls: RequireAndVerifyClientCert is not working as intended. #63120 (closed)
• crypto/tls: client did not fail when lack of a certificate and server requires one #59012 (closed)
• import/path: issue title #69986 (closed)
• crypto/tls: client auth failure alert codes can be improved #52113 (closed)
• crypto/tls: Dial to server with invalid client certificates succeeds and allows writes on tip, but not in 1.12 #32202 (closed)
• crypto/tls: incompatibility with Trust Settings in CA certificate #31881
• crypto/tls: handshake error with custom/local CA (bad record MAC & certificate signed by unknown authority) #4728 (closed)
• crypto/tls: improve invalid client certificate error message #35190 (closed)

Related Discussions

• crypto/tls: Misleading "remote error: tls: certificate required" error when client cert CA not in server's accepted CAs list

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

[rittneje]

When the server requests a client certificate (for mTLS), it lists the acceptable roots CAs. The RFC for TLS 1.3 specifically requires that the client respond with an empty certificate list if it has no matching certificate.

The client MUST send a Certificate message if and only if the server
has requested client authentication via a CertificateRequest message
(Section 4.3.2). If the server requests client authentication but no
suitable certificate is available, the client MUST send a Certificate
message containing no certificates (i.e., with the "certificate_list"
field having length 0).

The reason the client doesn't just "give up" in this situation is because it is possible the server does not mandate client auth (e.g., tls.VerifyClientCertIfGiven).

With regards to TLS 1.2, to my knowledge the Go TLS client has never sent a client certificate if it didn't match one of the acceptable CAs. However, I think TLS 1.2 does not mandate the server send the list of acceptable CAs at all, and in that case the Go client maybe just sends it. Perhaps HAProxy does not send it under 1.2 but does under 1.3, leading to the change in behavior?

In any case, I guess the Go TLS client could say that if the tls.Config has a certificate in it, and if it specifically receives a "certificate required" alert from the server, then it could augment the error to clarify that it's probably because the client certificate is not signed by one of the server's CAs.

[vinnie-v]

Appreciate the implementation follows the RFC specification

We use the verify required option in our HAProxy frontend to enforce client auth:
https://www.haproxy.com/documentation/haproxy-configuration-manual/latest/#verify

With regards to TLS 1.2, to my knowledge the Go TLS client has never sent a client certificate if it didn’t match one of the acceptable CAs. However, I think TLS 1.2 does not mandate the server send the list of acceptable CAs at all, and in that case the Go client maybe just sends it. Perhaps HAProxy does not send it under 1.2 but does under 1.3, leading to the change in behavior?

Here are two screenshots of a PCAP showing a TLS 1.2 handshake terminated by HAProxy that shows the server sending a CertificateRequest with a list of acceptable CAs - the Go client sends the certificate:

We don't always have control of the server when using mTLS and an indication of why the certificate was not sent would be useful in debugging. Maybe the error could be augmented to something like:
remote error: tls: certificate required (client certificate may not be signed by an acceptable CA)