Go tls.Config.GetConfigForClient 怎样按请求动态选择 TLS 配置

我在给 Go 服务接入多租户证书时，最初把 GetConfigForClient 当成了“只返回一张证书”的回调。后来发现它真正改变的是这条 TLS 连接要使用的整份 tls.Config。服务端收到 ClientHello 后，回调可以按 ServerName、SupportedProtos 等信息返回配置；返回 nil 就沿用原配置，返回错误则终止握手。

官方地址：https://pkg.go.dev/crypto/tls#Config.GetConfigForClient

实用的设计是：启动服务前准备好几份只读的服务端配置，在回调里只做轻量匹配和返回。不要在回调返回配置后继续修改它，也不要把会话恢复时的校验行为误认为每次都会重新执行。

GetConfigForClient 的参数和选择范围

GetConfigForClient 在服务端收到客户端的 ClientHello 后调用。参数 *tls.ClientHelloInfo 不是一个可随意读写的连接对象：它提供 ServerName、SupportedProtos、SupportedVersions 等握手信息，但不要从 Conn 里读写数据，否则会破坏 TLS 连接。

下面的写法把“匹配规则”和“配置对象”分开。未知域名返回 nil, nil，表示回到父配置；如果业务要求未知租户直接拒绝，可以把它改成返回一个错误。

package main

import (
	"crypto/tls"
	"fmt"
	"strings"
)

func buildServerConfig(apiCert, webCert tls.Certificate) *tls.Config {
	// 先准备不会在握手回调里修改的配置对象。
	profiles := map[string]*tls.Config{
		"api.example.com": {
			MinVersion:   tls.VersionTLS13,
			Certificates: []tls.Certificate{apiCert},
		},
		"www.example.com": {
			MinVersion:   tls.VersionTLS13,
			Certificates: []tls.Certificate{webCert},
		},
	}

	return &tls.Config{
		MinVersion: tls.VersionTLS13,
		GetConfigForClient: func(chi *tls.ClientHelloInfo) (*tls.Config, error) {
			// 去掉末尾点，避免同一主机名出现两种 map 键。
			name := strings.ToLower(strings.TrimSuffix(chi.ServerName, "."))
			if cfg, ok := profiles[name]; ok {
				// 返回已冻结的配置，不在这里继续修改 cfg。
				return cfg, nil
			}
			// nil 表示沿用传给 tls.Server 的原始配置。
			return nil, nil
		},
	}
}

func rejectUnknownTenant(chi *tls.ClientHelloInfo) (*tls.Config, error) {
	// 业务若不允许回退，可以用 error 让握手失败并保留原因。
	return nil, fmt.Errorf("unknown TLS server name: %s", chi.ServerName)
}

这里的关键不是把所有逻辑塞进回调，而是让回调只承担“读取握手信息并选配置”。证书加载、配置组装和共享 map 应在服务启动前完成；回调只读这些对象，才能避免握手高峰期出现锁竞争或配置半更新。

返回 nil、配置和 error 分别意味着什么

这个回调有三种结果，最好在接口设计时就写成明确的策略表：

官方文档还特别强调：回调返回的配置之后不能再修改。对我来说，最稳妥的做法是把它当作发布前生成的不可变快照。如果确实要从父配置派生，使用 Config.Clone 生成副本，在交给服务使用前一次性填好字段，然后不再触碰。

动态配置不是动态修改，回调也不等于证书校验

如果只需要按 SNI 选证书，GetCertificate 的职责更窄；如果需要同时改变 NextProtos、客户端认证策略或其它 TLS 参数，才更适合返回整份 *tls.Config。两者都接收 ClientHelloInfo，但不要为了“看起来灵活”而让回调承担证书解析、远程请求和长时间阻塞。

还有一个容易漏掉的边界：VerifyPeerCertificate 不会在恢复的连接上调用，官方文档明确提示这也包括跨父配置、兄弟配置或 GetConfigForClient 返回配置的会话恢复。如果每条连接都必须经过额外约束，应把关键检查放到 VerifyConnection，或者按业务需要设置 SessionTicketsDisabled。

上线前我会保留的四个检查点

1. 域名匹配是否统一大小写和末尾点，默认站点与未知域名策略是否明确。
2. 回调是否只读取 ClientHelloInfo，没有从 Conn 读写或执行不可控的远程调用。
3. 返回的配置是否在服务启动前准备好，发布后没有被另一个 goroutine 改写。
4. 是否区分新握手与会话恢复，并把必须覆盖恢复连接的约束放到 VerifyConnection。

如果你的需求只是“不同域名使用不同证书”，先从 GetCertificate 或静态 Certificates 开始；只有配置本身需要随 ClientHello 改变时，才引入 GetConfigForClient。这样回调更短，错误模型也更容易维护。

相关问题

返回的 tls.Config 可以在下一次请求前修改吗？

不建议，也不符合文档给出的使用边界。把它当成不可变配置快照，需要变化时重新构造或克隆一份，再在交给连接前完成设置。

未知 ServerName 一定要返回 error 吗？

不一定。返回 nil, nil 会回退到原始配置；多租户服务若不能接受默认站点，则应显式返回错误，让握手失败。