Go crypto/tls 自定义 CurvePreferences 后 ML-KEM 没启用怎么办

如果你在 Go 1.24 或更高版本里把 tls.Config.CurvePreferences 从默认的 nil 改成了自定义切片，ML-KEM 没有出现在握手里，通常不是 ML-KEM 失效，而是显式列表把默认集合替换掉了。解决方式是把需要的混合组明确写回列表，并确认客户端、服务端和 TLS 版本都有交集。

官方资料：https://pkg.go.dev/crypto/tls@go1.27.3#Config

空的 CurvePreferences 使用 Go 的默认集合；非空的 CurvePreferences 只启用列表中出现的密钥交换机制。要使用 X25519MLKEM768，就显式写入它，同时按对端兼容性保留 X25519 或 P-256。

• 默认语义：Go 1.24 起，字段为 nil 时默认包含 X25519MLKEM768；Go 1.26 起又增加了两种 SecP 混合组。
• 覆盖语义：一旦写入自定义列表，未列出的 ML-KEM 组就不会被启用。
• 协议边界：这些后量子混合组只用于 TLS 1.3，TLS 1.2 不会协商它们。

为什么一改 CurvePreferences，默认 ML-KEM 就消失了

我第一次遇到这个现象时，配置里只有 tls.X25519 和 tls.CurveP256，代码看起来很稳，握手也能成功，于是误以为对端不支持后量子交换。真正的变化发生在本地：CurvePreferences 不再是 nil 后，crypto/tls 不会把默认组自动追加回来。

这里还有一个容易混淆的点：字段名沿用了“Curve”，但它实际描述的是 TLS 密钥交换机制集合。X25519MLKEM768 是 X25519 与 ML-KEM-768 的混合组，不是把传统 X25519 静默升级成另一种算法。显式列表只表达“允许哪些机制”，列表顺序也不等于最终选择顺序。

把 X25519MLKEM768 写回自定义列表

如果目标是明确允许 X25519MLKEM768，可以直接把它放进列表。下面的配置同时保留传统 X25519 和 P-256，方便面对尚未支持混合组的服务端。是否保留它们取决于你的兼容范围，不要为了“启用后量子”而删除所有回退。

package main

import "crypto/tls"

func clientTLSConfig() *tls.Config {
	return &tls.Config{
		// 显式列表会覆盖默认集合，因此把需要的混合组写进去。
		CurvePreferences: []tls.CurveID{
			tls.X25519MLKEM768, // X25519 与 ML-KEM-768 的混合密钥交换
			tls.X25519,         // 为暂不支持混合组的对端保留传统回退
			tls.CurveP256,      // 继续兼容只提供 P-256 的 TLS 1.3 对端
		},
		// ML-KEM 混合组只用于 TLS 1.3，避免把协议版本期待混在一起。
		MinVersion: tls.VersionTLS13,
	}
}

服务端也可以设置同样的列表，但双方最终必须存在共同机制。客户端写入了 X25519MLKEM768，不代表服务端一定会选择它；如果服务端只允许 tls.X25519，握手仍可能成功，只是协商结果会回到传统组。

按三层边界排查“没有启用”

如果你只想使用默认集合，最简单的做法是不要给 CurvePreferences 赋值，让它保持 nil。若为了兼容性必须自定义，就把目标组和传统回退一起列出。GODEBUG=tlsmlkem=0 适用于调整默认行为，但它不能替代对显式列表语义的理解。

如何复查配置目标

复查时不要只观察“连接成功”。连接成功只能说明双方找到了某种共同机制，不能证明就是 ML-KEM。把测试拆成两个目标：先确认自定义列表没有漏写目标组，再用受控的 TLS 1.3 对端检查双方实际选择。如果生产环境必须强制某一种机制，应把允许列表收窄，并接受旧对端无法连接的结果。

// 读取握手后的状态，确认协议版本和对端证书等公开结果。
state := conn.ConnectionState()
if state.Version != tls.VersionTLS13 {
	// TLS 1.2 不会协商 X25519MLKEM768 这类 TLS 1.3 混合组。
	return fmt.Errorf("unexpected TLS version: 0x%x", state.Version)
}

// 这里不能仅凭连接成功推断具体 CurveID；应结合受控对端和握手调试信息复查。
log.Printf("negotiated protocol: %s", state.NegotiatedProtocol)

上面的状态读取只说明如何保留协议版本这个复查点，并没有把不存在的 CurveID 字段硬塞进 ConnectionState。实际排障时，最有价值的证据仍是两端的允许集合、TLS 版本和可重复的对端能力。

常见问题

只写 tls.X25519MLKEM768 是否可以？

可以表达“只允许这一种机制”，但所有对端都必须支持它；如果还要兼容传统 TLS 1.3 对端，就应把 X25519 或其他允许的组一并写入。

CurvePreferences 切片的第一个元素是不是优先级最高？

不是。Go 文档明确说明列表顺序会被忽略，内部偏好顺序负责选择；切片内容决定允许范围。

为什么 TLS 1.2 服务端看不到 ML-KEM？

因为这些混合密钥交换机制属于 TLS 1.3 范围。先确认双方没有把最大版本限制在 TLS 1.2，再检查自定义列表和对端支持情况。

这次问题的关键不是“再加一个开关”，而是分清默认集合与显式集合：保持 nil 就接受 Go 的默认策略，显式配置就把目标机制写完整；随后再用 TLS 版本和双方交集判断握手结果。