Go crypto/tls 怎样显式启用 ML-KEM 密钥交换

如果项目使用 Go 1.27，想让 TLS 连接明确尝试 ML-KEM-1024，入口就是 tls.Config.CurvePreferences：把 tls.MLKEM1024 放进这个切片，并根据对端兼容性保留一个经典算法作为回退。这里的“显式启用”是扩大或收窄本端允许的密钥交换集合，不是强行命令对端必须使用某一个组。

官方文档：https://pkg.go.dev/crypto/tls

先分清默认集合和显式集合

Go 的 CurvePreferences 名字沿用了椭圆曲线时代的叫法，实际承载的是 TLS 密钥交换机制。Go 1.24 的默认集合已经包含 X25519MLKEM768，Go 1.26 又加入了两个基于椭圆曲线的混合组；Go 1.27 进一步支持 MLKEM1024。因此，配置为 nil 并不等于“没有后量子能力”。

真正需要显式配置的场景通常有两个：一是要把 MLKEM1024 纳入自己的兼容性矩阵，二是要限制本端只允许经过评估的几个组。显式切片会成为支持集合，不能只凭“默认值里可能有它”来判断结果。

客户端和服务端怎样写配置

下面的示例保留 MLKEM1024、X25519MLKEM768 和 X25519。前两个用于后量子混合交换，最后一个给尚未支持 ML-KEM 的对端留下 TLS 1.3 的经典回退。

package main

import "crypto/tls"

func tlsConfig() *tls.Config {
	return &tls.Config{
		// 只接受 TLS 1.3，避免把本例的密钥交换选择带到旧协议路径。
		MinVersion: tls.VersionTLS13,
		// 这是允许集合，不是把第一个元素当成强制优先级。
		CurvePreferences: []tls.CurveID{
			tls.MLKEM1024,
			tls.X25519MLKEM768,
			tls.X25519,
		},
	}
}

客户端可以把返回值交给 tls.Dial 或 http.Transport.TLSClientConfig；服务端则交给 tls.Listen 或 HTTP Server 的 TLS 配置。双方都必须拥有可匹配的组，单方面加入 MLKEM1024 不会让不支持它的服务器自动获得该能力。

三种选择怎么取舍

注意，官方文档说明列表顺序会被内部偏好规则处理，不能把切片第一项理解成可靠的“强制首选”。如果产品要求只允许 MLKEM1024，应把集合收窄并让两端一起升级，而不是依赖排列顺序。

GODEBUG 和旧版本是两个边界

tlsmlkem=0、tlssecpmlkem=0 用于调整默认集合相关行为。当代码已经显式设置 CurvePreferences 时，应以代码里的集合为准；运维脚本里改环境变量不能替代配置审查。另一个现实问题是 tls.MLKEM1024 属于 Go 1.27 API，直接在更旧的工具链编译会报未定义，应该先升级构建镜像，或用构建标签隔离不同工具链的实现。

排查握手问题时，先记录客户端和服务端的 Go 版本、实际配置是否为 nil、是否设置了 GODEBUG，再确认双方集合是否有交集。不要先改密码套件：TLS 1.3 的密钥交换组与 TLS 1.2 密码套件是不同层次的配置。

常见问题

只写 MLKEM1024 就一定使用它吗？

不一定。它只是本端允许的集合，仍要经过 TLS 双端协商；若对端不支持，握手会失败或无法找到共同组。

为什么 GODEBUG 改了但结果没变？

先看 CurvePreferences 是否已经显式赋值。GODEBUG 主要作用于默认集合路径，显式列表不会因为环境变量自动补项。

需要把 X25519 放在最后吗？

不要把切片顺序当成强制优先级。是否保留 X25519，取决于兼容性目标；要做强约束就收窄集合，并同步升级通信双方。

实际落地时，推荐先使用“MLKEM1024 + 混合组 + X25519”的兼容集合，确认双方版本和协商结果后，再决定是否收窄范围。