Go crypto/mlkem 公钥和私钥怎样按字节格式保存与恢复

用 Go 的 crypto/mlkem 保存密钥时，应该保存 API 定义的字节表示，再用对应的 New... 构造函数恢复，而不是把带有未导出字段的密钥对象直接做通用序列化。解封装私钥的 Bytes() 返回 64 字节的 d || z 种子；封装公钥的 Bytes() 返回参数集对应的公钥编码。

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

这一区别决定了数据库字段、配置文件或密钥托管适配层应该保存什么。下面只讨论字节往返、参数集和长度边界，不展开具体网络协议封装。

先把“私钥”和“公钥”对应到 ML-KEM 类型

在 ML-KEM 的命名里，解封装密钥是需要保密的私钥对象，类型是 DecapsulationKey768 或 DecapsulationKey1024；封装密钥是可以交给对端的公钥对象，类型是 EncapsulationKey768 或 EncapsulationKey1024。

私钥对象可以通过 EncapsulationKey() 得到相同参数集的公钥对象。这个方法返回的是公钥对象，不是把私钥字节截取一段当成公钥。两个对象各自有 Bytes()，也各自有匹配的 New... 恢复函数。

Bytes 返回的不是任意内存快照

DecapsulationKey768.Bytes() 和 DecapsulationKey1024.Bytes() 都返回 64 字节种子，官方文档把它描述为 d || z 形式。恢复时必须把这 64 字节交给同一个参数集的 NewDecapsulationKey768 或 NewDecapsulationKey1024。

封装公钥则不同：EncapsulationKey768.Bytes() 返回 ML-KEM-768 的公钥编码，EncapsulationKey1024.Bytes() 返回 ML-KEM-1024 的公钥编码。它们不是 64 字节种子，也不能交给解封装密钥的构造函数。

因此，持久化层至少要和字节一起记录参数集，例如把 mlkem-768 或 mlkem-1024 作为独立字段。单看一个字节列，调用方无法可靠判断它应该使用哪个构造函数。

先固定参数集，再处理长度

官方常量给出了公钥和密文的尺寸。两种参数集的私钥 Bytes() 都是 64 字节，但封装公钥和密文长度会随参数集变化：

长度检查适合做快速的输入分类，但不能替代构造函数的错误处理。尤其是公钥，长度正确只说明它有机会进入解析流程，最终仍要以 NewEncapsulationKey... 的返回错误为准。

最小往返示例：保存 Bytes，再用 New 恢复

下面的示例把字节写入内存变量来模拟数据库或密钥存储层。实际落盘时，还应把参数集和密钥用途一起保存；示例没有把真实私钥打印出来。

package main

import (
	"bytes"
	"crypto/mlkem"
	"fmt"
)

func main() {
	// 生成私钥对象；真实应用中不要把私钥字节写入日志。
	dk, err := mlkem.GenerateKey768()
	if err != nil {
		panic(err)
	}

	// Bytes 返回可持久化的 64 字节 d || z 种子。
	privateBytes := dk.Bytes()
	if len(privateBytes) != mlkem.SeedSize {
		panic("私钥种子长度不符合 ML-KEM 约定")
	}

	// 用同一参数集的构造函数恢复解封装密钥。
	restoredDK, err := mlkem.NewDecapsulationKey768(privateBytes)
	if err != nil {
		panic(err)
	}

	// 从私钥派生公钥，再保存公钥的官方编码形式。
	ek := restoredDK.EncapsulationKey()
	publicBytes := ek.Bytes()
	if len(publicBytes) != mlkem.EncapsulationKeySize768 {
		panic("公钥编码长度不符合 ML-KEM-768")
	}

	// 公钥用匹配的 NewEncapsulationKey 函数恢复。
	restoredEK, err := mlkem.NewEncapsulationKey768(publicBytes)
	if err != nil {
		panic(err)
	}

	// 再次取出编码，只比较编码是否一致，不输出密钥内容。
	privateRoundTrip := bytes.Equal(privateBytes, restoredDK.Bytes())
	publicRoundTrip := bytes.Equal(publicBytes, restoredEK.Bytes())
	fmt.Printf("private=%t public=%t\n", privateRoundTrip, publicRoundTrip)
}

这里的 bytes.Equal 只用于说明编码往返是否保持一致。它不是协议握手，也不代表已经验证了某个外部密钥文件的来源；外部输入仍要经过构造函数并检查错误。

换成 ML-KEM-1024 时，调用链也要一起换

如果业务选择 ML-KEM-1024，不能只把长度常量改成 EncapsulationKeySize1024，而保留 768 的构造函数。生成、恢复私钥、派生公钥、恢复公钥必须在同一参数集内闭合：

// 选择 1024 参数集后，生成和恢复函数必须成套使用。
dk, err := mlkem.GenerateKey1024()
if err != nil {
	panic(err)
}

// 私钥仍然是 64 字节 d || z，但解释方式由 1024 构造函数决定。
privateBytes := append([]byte(nil), dk.Bytes()...)
restoredDK, err := mlkem.NewDecapsulationKey1024(privateBytes)
if err != nil {
	panic(err)
}

// 1024 的公钥编码长度是另一组常量，不能拿 768 的长度判断。
publicBytes := restoredDK.EncapsulationKey().Bytes()
if len(publicBytes) != mlkem.EncapsulationKeySize1024 {
	panic("公钥编码长度不符合 ML-KEM-1024")
}
restoredEK, err := mlkem.NewEncapsulationKey1024(publicBytes)
if err != nil {
	panic(err)
}
_ = restoredEK

注意，私钥种子长度相同并不意味着 768 和 1024 的私钥可以互换。相同的 64 字节输入由不同参数集展开，会得到不同的密钥对象；参数集字段不能省略。

错误处理要放在恢复边界

NewDecapsulationKey... 会根据输入种子构造私钥对象，输入长度不符合要求时应直接返回错误。NewEncapsulationKey... 用于解析公钥编码，非法公钥也必须保留错误，不要在存储层截断、补零或静默替换。

一个常见误区是只用长度判断公钥，然后把字节交给后续逻辑。长度判断可以提前拒绝明显错误的输入，但真正的格式和合法性边界由对应的 NewEncapsulationKey... 决定。恢复失败时，推荐保留参数集、字段用途和错误上下文，避免把“公钥解析失败”误报成“网络协商失败”。

保存时的几条实际规则

• 私钥字节属于秘密材料，不能写入普通日志、错误消息或公开配置。
• 公钥可以分发，但仍要保留参数集和用途，避免 768/1024 混用。
• 保存二进制时优先使用数据库二进制字段或明确的 Base64/Hex 编码；不要依赖 Go 私有字段布局。
• 恢复后再次调用 Bytes() 做编码往返核对即可；不要把这一步扩展成未被要求的线上校验。
• 不要把密文或共享密钥当成公钥保存。它们属于后续封装过程的数据，长度和保密属性都不同。

结论

Go crypto/mlkem 的字节往返可以记成两条配对规则：解封装密钥使用 Bytes() 与同参数集的 NewDecapsulationKey...，封装公钥使用 Bytes() 与同参数集的 NewEncapsulationKey...。私钥字节是 64 字节种子，公钥字节长度随 ML-KEM-768/1024 改变；长度检查只能做快速筛选，最终必须处理构造函数错误。

相关问题

为什么不能用 JSON 直接序列化 DecapsulationKey？因为关键字段是未导出的内部状态，通用 JSON 序列化不能替代官方的 64 字节种子格式。

公钥长度正确就一定能恢复吗？不一定。长度只是初筛，仍应调用匹配的 NewEncapsulationKey... 并检查错误。

ML-KEM-768 和 ML-KEM-1024 可以共用同一列字节吗？可以共用存储类型，但必须额外保存参数集，并按参数集选择完整的生成、恢复和长度常量。