crypto/hpke 选择 KEM 与 AEAD 组合的配置思路

Go 1.26 把 HPKE（Hybrid Public Key Encryption）放进标准库后，配置不再只是“选一个加密算法”。一个 HPKE ciphersuite 由 KEM、KDF 和 AEAD 共同决定：KEM 负责封装共享秘密，KDF 负责从共享秘密派生会话材料，AEAD 负责对消息做带认证的加密。三个组件要按密钥来源、兼容对象、后量子目标和运行环境一起选择。

官方地址：https://pkg.go.dev/crypto/hpke

实用的默认思路是：已有 X25519 密钥且优先兼容时从 DHKEM(ecdh.X25519()) 开始；需要后量子能力时考虑 MLKEM768() 或 MLKEM768X25519()；KDF 优先使用与 KEM 规范匹配的 HKDF；AEAD 则根据硬件加速、平台差异和协议要求在 AES-GCM 与 ChaCha20-Poly1305 中选择。不要把 ExportOnly() 当成普通消息加密方案。

先看 KEM：决定密钥封装的边界

KEM 是三个组件中最先要定下来的部分，因为它同时影响密钥格式、封装结果长度、接收端密钥来源和可迁移路径。Go 的 crypto/hpke 提供 DHKEM、ML-KEM，以及把经典曲线与 ML-KEM 组合起来的混合 KEM。

DHKEM(ecdh.X25519()) 适合已经采用 X25519、需要较小密钥材料和成熟互操作边界的系统。P-256、P-384、P-521 也能通过 DHKEM 选择，但它们对应的 HKDF 组合并不相同：P-256 对应 HKDF-SHA256，P-384 对应 HKDF-SHA384，P-521 对应 HKDF-SHA512，X25519 对应 HKDF-SHA256。

MLKEM768() 与 MLKEM1024() 面向纯后量子 KEM。若通信两端或中间协议还处在迁移阶段，MLKEM768X25519() 这类混合 KEM 更适合作为过渡候选：它同时依赖 ML-KEM-768 和 X25519，只有当两部分都按约定完成时才形成共享结果。混合并不等于可以忽略两套密钥的生命周期，密钥轮换、序列化和对端能力协商仍要单独设计。

选择顺序可以固定成下面三问：

1. 对端能否理解同一种 KEM 的公钥和封装结果？不能就先解决协议兼容，而不是换 AEAD。
2. 系统是兼容优先、纯后量子，还是需要渐进迁移？这决定 DHKEM、ML-KEM 或混合 KEM 的方向。
3. 密钥来自 Go 内存、硬件模块还是外部实现？如果是外部密钥，优先确认 NewDHKEMPrivateKey、NewHybridPrivateKey 等适配入口是否符合现有接口。

为什么不能把 KDF 当成独立下拉框

KDF 的职责是把 KEM 产生的共享秘密扩展为 HPKE 上下文需要的密钥和 nonce。虽然 API 把 KDF 单独表示为 hpke.KDF，但 KEM 的定义已经包含了它的匹配关系。比如 DHKEM(P-256) 的规范组合是 HKDF-SHA256，而 DHKEM(X25519) 也是 HKDF-SHA256；这不是因为所有 KEM 都只能使用 SHA256，而是因为具体 HPKE KEM 套件规定了对应的哈希。

如果业务确实需要运行时按 ID 读取配置，可以用 NewKEM、NewKDF 和 NewAEAD，但要把允许的三元组写成白名单。不要接收三个任意的整数 ID 后直接拼装，因为“每个 ID 单独有效”不代表组合后的协议标识、对端实现和互操作测试都有效。

package main

import "crypto/hpke"

// Suite 描述一个经过业务白名单筛选的 HPKE 配置。
type Suite struct {
	KEM  hpke.KEM
	KDF  hpke.KDF
	AEAD hpke.AEAD
}

func defaultSuite() Suite {
	// X25519 的 DHKEM 与 HKDF-SHA256 是文档规定的匹配组合。
	return Suite{
		KEM:  hpke.DHKEM(ecdh.X25519()),
		KDF:  hpke.HKDFSHA256(),
		AEAD: hpke.ChaCha20Poly1305(),
	}
}

上面的示例还需要导入 crypto/ecdh；这里把配置结构和选择意图放在一起，是为了避免调用方在不同文件里分别替换三个组件。生产代码还应为每个允许的 suite 设定稳定名称，日志只记录名称和版本，不记录私钥内容。

AEAD 选择：先看平台，再看协议用途

Go 的 HPKE 文档提供 AES-128-GCM、AES-256-GCM 和 ChaCha20-Poly1305。它们都承担消息机密性与完整性，但部署条件不同：

AEAD 的决定仍然要受协议约束。若对端能力协商已经把 suite 固定为 AES-256-GCM，发送端不能为了本机速度偷偷换成 ChaCha20-Poly1305；这会让双方的 HPKE 上下文不一致。更稳妥的做法是把 suite 名称放进协议版本或能力协商字段，在收到未知名称时拒绝，而不是猜一个默认值。

把选择固化到 Seal/Open 的最小闭环

确定组合后，先用 one-shot API 建立一个最小闭环。它适合单条消息或不需要复用上下文的场景：接收端生成私钥并暴露公钥，发送端用公钥封装并加密，接收端再用私钥解密。官方示例使用 MLKEM768-X25519、HKDF-SHA256 和 AES-256-GCM；下面把同一思路改成可替换 suite 的函数。

package main

import (
	"crypto/ecdh"
	"crypto/hpke"
	"fmt"
)

func roundTrip() error {
	// KEM、KDF、AEAD 必须在发送端和接收端使用同一组配置。
	kem := hpke.MLKEM768X25519()
	kdf := hpke.HKDFSHA256()
	aead := hpke.AES256GCM()
	info := []byte("orders/v1")

	// 接收端生成私钥，只把序列化后的公钥交给发送端。
	recipientKey, err := kem.GenerateKey()
	if err != nil {
		return fmt.Errorf("生成接收端密钥: %w", err)
	}
	publicKey, err := kem.NewPublicKey(recipientKey.PublicKey().Bytes())
	if err != nil {
		return fmt.Errorf("解析接收端公钥: %w", err)
	}

	// 发送端返回的 ciphertext 内含封装结果和 AEAD 密文。
	ciphertext, err := hpke.Seal(publicKey, kdf, aead, info, []byte("order-123"))
	if err != nil {
		return fmt.Errorf("封装并加密: %w", err)
	}

	// 接收端必须使用对应私钥、同一套件和完全一致的 info。
	plaintext, err := hpke.Open(recipientKey, kdf, aead, info, ciphertext)
	if err != nil {
		return fmt.Errorf("解密: %w", err)
	}
	fmt.Printf("%s\\n", plaintext)
	return nil
}

var _ = ecdh.X25519 // 业务切换为 DHKEM 时可用该曲线构造 KEM。

示例中的 info 是公开的上下文绑定信息，不是密码。它必须在两端一致，通常可以包含协议名、版本、租户或消息用途；若不同，Open 应该失败。真实项目还要把 KEM 公钥的序列化格式、封装结果的长度和消息 framing 写进协议，而不是只传一段无边界的字节串。

状态化 API 和运行时配置怎么选

如果一条会话会连续处理多条消息，可以使用 NewSender 和 NewRecipient 创建状态化上下文。Sender.Seal 与 Recipient.Open 会维护内部计数器，接收端的调用顺序必须与发送端匹配。因此不要把同一个上下文无锁地交给多个并发 worker，也不要在消息重排后继续复用它；要么按顺序消费，要么为每个独立方向建立上下文。

运行时配置建议拆成两层：

• 协议层只允许固定的 suite 名称，例如 mlkem768-x25519-hkdf-sha256-aes256gcm，并对未知名称直接报错。
• 实现层把名称映射到已经配对的 hpke.KEM、hpke.KDF 和 hpke.AEAD，禁止调用方分别覆盖其中一个组件。

type SuiteFactory func() (hpke.KEM, hpke.KDF, hpke.AEAD, error)

var suites = map[string]SuiteFactory{
	"x25519-hkdf-sha256-chacha20poly1305": func() (hpke.KEM, hpke.KDF, hpke.AEAD, error) {
		// 把匹配关系集中登记，避免配置文件拼出未知组合。
		return hpke.DHKEM(ecdh.X25519()), hpke.HKDFSHA256(), hpke.ChaCha20Poly1305(), nil
	},
	"mlkem768x25519-hkdf-sha256-aes256gcm": func() (hpke.KEM, hpke.KDF, hpke.AEAD, error) {
		// 混合 KEM 的 suite 名称明确表达两种密钥成分。
		return hpke.MLKEM768X25519(), hpke.HKDFSHA256(), hpke.AES256GCM(), nil
	},
}

如果使用这段工厂代码，文件顶部还需要导入 crypto/ecdh。示例特意没有把 ID 直接暴露给配置文件：只有确实需要与外部协议按数值协商时，才在边界层用 NewKEM、NewKDF 和 NewAEAD 做严格的 ID 到 suite 映射。

最小核对：确认组合、上下文和失败路径

在接入正式协议前，至少保留以下核对项。它们用于确认本地配置和对端约定一致，不代表对密码方案做完整安全审计。

1. 打印或记录 suite 名称，而不是私钥、公钥原文或密文内容。
2. 用一条固定测试消息完成一次 Seal/Open；故意改变 info、AEAD 或 KEM 后应得到错误。
3. 确认公钥、封装结果和密文的 framing 能在网络传输中区分，避免把截断或拼接错误误判成算法不兼容。
4. 对 ExportOnly 单独写派生密钥测试，不把它放进消息加密的通用配置。
5. 如果启用后量子或混合 KEM，记录 Go 版本、对端库版本和协议协商值，以便未来迁移时定位兼容边界。

最后可以用一句话做决策：兼容优先选匹配现有密钥体系的 DHKEM，后量子目标选 ML-KEM，迁移期选混合 KEM；KDF 跟随 KEM 的规范配对，AEAD 再根据平台与协议选定，并把三者封装成不可随意拆改的 suite。

相关问题

crypto/hpke 的 KEM、KDF、AEAD 可以任意组合吗？

API 层允许把接口作为参数传入，但协议层不应把三个组件当作完全独立的自由组合。至少要遵守 KEM 与 KDF 的规范匹配关系，并用固定 suite 白名单保证对端可互操作。

什么时候用 MLKEM768X25519 而不是 MLKEM768？

当系统处于后量子迁移期、还希望保留 X25519 的经典密钥交换成分时，可以评估混合 KEM。若协议已经明确要求纯后量子 KEM，则应按协议规定选择 ML-KEM，而不是自行替换。

ExportOnly 能不能当作 AES-GCM 的替代品？

不能。ExportOnly 只用于导出共享秘密，Sender.Seal 和 Recipient.Open 会返回错误。需要加密消息时应选择 AES-GCM 或 ChaCha20-Poly1305。