crypto/mlkem 生成密钥对后的序列化流程

用 Go 的 crypto/mlkem 生成密钥后，真正需要保存的不是一个可以直接 JSON 化的结构体，而是 API 明确提供的字节表示：私钥侧保存 DecapsulationKey.Bytes() 返回的 64 字节 d || z 种子，公钥侧保存 EncapsulationKey.Bytes() 返回的编码字节。恢复时分别调用对应的 NewDecapsulationKeyXXX 和 NewEncapsulationKeyXXX。

我整理这条链路时会先建立三个基线：序列化后的长度、恢复密钥对象的耗时、输入不合法时的错误率。这样可以把“字节能不能存下来”和“业务链路是否满足性能预算”分开讨论。

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

先分清 DecapsulationKey 和 EncapsulationKey

crypto/mlkem 实现的是 ML-KEM，Go 1.24 的标准库已经提供 ML-KEM-768 和 ML-KEM-1024。它不是传统意义上把一把私钥和一把公钥都暴露为同一种结构：DecapsulationKey 是持有方用于解封装的秘密对象，EncapsulationKey 是发送方用于封装的公开对象。

生成入口返回的是解封装密钥。再通过 dk.EncapsulationKey() 得到对应的公开密钥，随后两个对象各自用 Bytes() 输出可保存的表示。这个对应关系很重要：不要把私钥的字节放入配置中心后又按公钥构造函数解析，也不要把公钥编码当成可以保密的私钥材料。

生成 ML-KEM-768 并导出两种字节

下面的示例选择官方文档推荐作为常见起点的 ML-KEM-768。示例只打印长度和恢复结果，不打印任何密钥内容；在真实服务中也应避免把私钥种子、共享密钥或密文写入普通日志。

package main

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

func main() {
	// GenerateKey768 使用安全随机源生成解封装密钥。
	dk, err := mlkem.GenerateKey768()
	if err != nil {
		log.Fatal(err)
	}

	// Bytes 返回 64 字节 d || z 私钥种子，必须按秘密材料保护。
	secretSeed := dk.Bytes()

	// EncapsulationKey 返回对应的公开封装密钥。
	ek := dk.EncapsulationKey()
	publicKey := ek.Bytes()

	// 只记录长度，避免把密钥内容写进日志或监控标签。
	fmt.Printf("secret_seed_bytes=%d public_key_bytes=%d\\n", len(secretSeed), len(publicKey))
}

对 ML-KEM-768，私钥侧的种子长度是 64 字节，公开封装密钥的编码长度是 1184 字节。这里的“序列化”是 API 规定的字节表示，不是把 Go 结构体字段通过 encoding/json 展开；内部预计算值由构造函数根据种子重新建立。

用对应的 New*Key 恢复对象

恢复流程需要保留参数集：768 的字节只能交给 768 的构造函数，1024 也同理。公钥构造函数会解析编码并在格式无效时返回错误；私钥构造函数要求输入是均匀随机的 64 字节 d || z 种子。业务层应把这些错误当成密钥材料损坏或版本配置错误处理，不能静默换用另一套参数。

package main

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

func restore768(secretSeed, publicKey []byte) (*mlkem.DecapsulationKey768, *mlkem.EncapsulationKey768, error) {
	// 先用私钥种子恢复解封装对象；错误表示种子长度或内容不符合要求。
	dk, err := mlkem.NewDecapsulationKey768(secretSeed)
	if err != nil {
		return nil, nil, fmt.Errorf("restore decapsulation key: %w", err)
	}

	// 再解析公开封装密钥；公钥损坏时不要继续进入封装流程。
	ek, err := mlkem.NewEncapsulationKey768(publicKey)
	if err != nil {
		return nil, nil, fmt.Errorf("restore encapsulation key: %w", err)
	}
	return dk, ek, nil
}

func main() {
	// 示例中的字节应来自受控存储；这里不硬编码真实密钥内容。
	secretSeed := loadSecretSeed()
	publicKey := loadPublicKey()
	dk, ek, err := restore768(secretSeed, publicKey)
	if err != nil {
		log.Fatal(err)
	}

	// 这里只证明对象可用于后续流程，不输出秘密值。
	_, ciphertext := ek.Encapsulate()
	sharedKey, err := dk.Decapsulate(ciphertext)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("ciphertext_bytes=%d shared_key_bytes=%d\\n", len(ciphertext), len(sharedKey))
}

// 生产实现应从密钥管理系统读取，而不是从源码或普通环境变量读取私钥。
func loadSecretSeed() []byte { return nil }

// 公钥可以从配置或服务发现数据读取，但仍要绑定算法和参数集。
func loadPublicKey() []byte { return nil }

上面的 loadSecretSeed 和 loadPublicKey 只是接口占位，不能直接运行出有效密钥。真正的工程重点在于保存时记录算法和参数集，恢复时校验长度并保留原始错误上下文。对发送方而言，只需要公钥；对解封装方而言，私钥种子才是必须严格保护的材料。

把长度、恢复耗时和失败率做成基线

密码 API 的性能讨论容易只看一次调用耗时，但序列化链路至少有三类指标：字节长度决定存储和传输成本，恢复耗时决定冷启动或密钥轮换成本，失败率则能暴露截断、参数集错配和编码损坏。

不要把上表当成业务压测结果，它只是 API 定义的长度基线。压测时应使用固定数量的合法样本和专门的错误样本，分别记录 p50、p95 恢复耗时，以及错误输入的分类计数；同时把参数集作为标签，而不是把 768 和 1024 混在一个平均值里。

跨进程保存时的安全边界

私钥种子和公钥编码的存储策略不应相同。私钥种子应进入具备访问控制、审计和轮换能力的密钥存储；公钥可以分发，但分发数据仍应带上算法名称、参数集和版本信息，避免接收方把不同参数集的字节误解析。

传输协议中可以把公钥作为注册或握手材料，把密文作为每次封装的结果；共享密钥只留在双方内存中，再交给后续对称加密流程。不要把 sharedKey 当作可长期保存的身份凭据，也不要把 DecapsulationKey.Bytes() 放进普通业务数据库的可读字段。

常见问题

为什么不能直接序列化 DecapsulationKey 结构体？

结构体包含未导出字段和预计算状态，官方 API 已经提供了稳定的字节表示与恢复函数。使用 Bytes 和 NewDecapsulationKeyXXX 才能明确保存格式和参数集。

768 的公钥能否交给 NewEncapsulationKey1024？

不能。参数集和编码长度必须匹配，应用应在数据旁边保存算法与参数集元数据，并在恢复失败时保留错误，不要自动切换构造函数。

为什么示例只打印长度？

长度足以用于序列化基线，密钥内容本身不应进入日志、监控标签或错误信息。生产环境还应对私钥种子和共享密钥设置更严格的内存与访问控制策略。

归纳起来，GenerateKey768 负责生成秘密的解封装密钥，EncapsulationKey 负责得到公开对象，两个 Bytes 分别产生可保存的私钥种子和公钥编码，两个 New*Key 再按同一参数集恢复对象。只要把这条对应关系固定下来，ML-KEM 的持久化、分发和性能基线就不会混在一起。