Go tls.Config.EncryptedClientHelloConfigList 的 ECH 客户端握手配置与失败处理

Go 客户端配置 ECH 时，核心不是把一个“开关”设成 true，而是把服务端发布的序列化 ECHConfigList 放入 tls.Config.EncryptedClientHelloConfigList，同时满足 TLS 1.3 约束。配置无效会在握手阶段直接失败；服务端拒绝 ECH 时也不会自动退回普通 TLS，而是返回可识别的 tls.ECHRejectionError。

官方资料：https://pkg.go.dev/crypto/tls

先把 ECH 配置和普通 TLS 配置分开

排障时最容易混淆的是职责边界：EncryptedClientHelloConfigList 是客户端拿来尝试 ECH 的序列化配置列表；服务端对应的是 EncryptedClientHelloKeys 或 GetEncryptedClientHelloKeys。它们都属于 crypto/tls，但不能把服务端字段塞进客户端，也不能拿任意字节切片冒充 ECHConfigList。

另外，ECH 不是普通连接复用，也不是 ClientSessionCache。这次握手是否使用 ECH，要看配置解析、TLS 版本和服务端回应；不要用连接池是否复用来判断 ECH 是否成功。

用 TLS 1.3 和真实配置构造客户端

下面的 echConfigList 代表通过可信发布渠道取得的序列化 ECHConfigList。代码展示配置关系，不提供伪造的字节常量；把随手写的十六进制数据放进去，只会得到“配置无法解析”一类的握手错误。

package main

import (
	"crypto/tls"
	"net"
	"time"
)

func dialECH(addr string, echConfigList []byte) (*tls.Conn, error) {
	// ECH 配置必须来自服务端发布的序列化 ECHConfigList，不能自行拼接占位字节。
	cfg := &tls.Config{
		ServerName:                     "public.example",
		MinVersion:                     tls.VersionTLS13,
		EncryptedClientHelloConfigList: echConfigList,
		// 保留普通证书校验；ECH 配置不是跳过证书校验的理由。
	}
	// 给 TCP 拨号设置边界，避免配置错误时一直占住调用方。
	d := &net.Dialer{Timeout: 5 * time.Second}
	conn, err := tls.DialWithDialer(d, "tcp", addr, cfg)
	if err != nil {
		// 返回原始握手错误，交给上层区分配置错误和服务端拒绝。
		return nil, err
	}
	return conn, nil
}

按握手阶段拆解失败信息

可以按下面的检查顺序缩小范围。第一类是本地配置解析失败，通常意味着列表为空、编码不是有效的 ECHConfigList，或配置与当前实现不兼容。第二类是版本约束：如果显式把 MinVersion 设成 TLS 1.2，ECH 配置就不满足要求。第三类才是服务端拒绝或外层 provider 证书校验失败。

处理 ECHRejectionError 的重试边界

服务端拒绝 ECH 时，Go 可能返回包含新配置的 RetryConfigList。它不是“任何失败都自动重试”的许可：只有确认来源可信、更新配置后仍满足 TLS 1.3，才适合重新发起一次握手。空的重试列表可以是服务端给出的安全信号，不能把它当作普通降级条件。

import (
	"crypto/tls"
	"errors"
)

func retryConfigFrom(err error) ([]byte, bool) {
	var rejection *tls.ECHRejectionError
	if !errors.As(err, &rejection) {
		// 不是 ECH 拒绝，交给普通网络或证书错误处理。
		return nil, false
	}
	if len(rejection.RetryConfigList) == 0 {
		// 没有可信的新列表时停止，不能把 ECH 降级成普通 TLS。
		return nil, false
	}
	// 上层还应校验配置来源，再把这份列表放入新的 tls.Config。
	return rejection.RetryConfigList, true
}

如果需要自定义 ECH 被拒绝时的外层 provider 证书校验，可使用 EncryptedClientHelloRejectionVerify。这个回调的调用时机不同于 VerifyConnection：ECH 被拒绝时，普通证书校验不会先于它完成；回调返回错误，握手立即终止。这里尤其不能用 InsecureSkipVerify 掩盖信任链问题。

上线前固定三条规则

1. 配置对象交给 TLS 函数后不要再修改；热更新时构造新的 tls.Config，避免并发读写同一份字节列表。
2. 记录配置来源、握手错误类型和是否发生 ECH 拒绝，但不要把完整私密材料写进日志。
3. 把 ECH 当成必须成功的安全策略时，不要静默降级；明确区分“拿到新 RetryConfigList 后重试”和“无可验证配置，安全终止”。

相关问题

EncryptedClientHelloConfigList 能在服务端配置吗？

不能。它是客户端字段；服务端应使用 EncryptedClientHelloKeys 或 GetEncryptedClientHelloKeys。

为什么设置了 ECH 配置后 TLS 1.2 握手失败？

只要客户端设置了 ECHConfigList，显式的 MinVersion 就必须是 TLS 1.3；TLS 1.2 不满足该配置约束。

收到 ECHRejectionError 是否应该立刻改成普通 TLS？

不应该。先检查是否有可信的 RetryConfigList；没有新配置时按安全策略终止，是否降级必须由业务安全边界明确决定。