crypto/hpke 将关联数据绑定到消息的实现方式

我第一次把 HPKE 接进消息封装时，最容易混在一起的是 info 和 aad：两者都是公开字节，却不在同一个阶段生效。实际做多租户消息时，租户编号、协议版本、消息序号不能放进明文里任人替换，但也没有必要把它们加密；更合适的做法是把它们编码成 aad，让接收端只有在这些字段完全一致时才能打开密文。

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

在 Go 的 crypto/hpke 中，info 用来让发送端和接收端建立同一个 HPKE 上下文，aad 则在每次 Seal/Open 时把公开元数据纳入认证范围。需要逐消息绑定时，应使用状态化的 Sender 与 Recipient，而不是只提供 info 的单次 Seal/Open。

先把 info、aad 和明文分成三类

Go 1.26 引入的 crypto/hpke 按 RFC 9180 提供 KEM、KDF 和 AEAD 的组合。API 里有三个容易被误用的输入：

• info：创建发送端和接收端上下文时都要一致，适合协议名、版本、用途这类在一个上下文内不变的信息。
• aad：每条消息都可以不同，适合租户、消息类型、序列号或路由版本等“公开但不能被替换”的字段。
• plaintext：真正需要保密的业务内容，调用 Seal 后形成密文。

我现在会先问一句“这个字段会不会随每条消息变化”。不变化的上下文约束放在 info，每条消息都要重新认证的字段放在 aad；两者都不负责替代密钥轮换、身份认证或业务层重放存储。

用状态化上下文绑定每条消息

单次 hpke.Seal 和 hpke.Open 的签名只有 info，官方文档明确说明这两个便捷函数不带 aad。需要关联数据时，先用接收方公钥创建 Sender，把返回的封装值 enc 交给接收方创建 Recipient，之后每条消息都调用状态化方法。

package main

import (
	"fmt"

	"crypto/ecdh"
	"crypto/hpke"
)

func main() {
	// 选择 KEM、KDF 和 AEAD；实际协议应把这组选择固定在版本协商中。
	kem := hpke.DHKEM(ecdh.X25519())
	kdf := hpke.HKDFSHA256()
	aead := hpke.ChaCha20Poly1305()

	// 接收方先生成私钥，私钥只留在接收方；发送方只需要对应公钥。
	recipientKey, err := kem.GenerateKey()
	if err != nil {
		panic(err)
	}

	// info 是上下文级参数，两端建立 Sender/Recipient 时必须逐字节一致。
	info := []byte("orders/v1")
	enc, sender, err := hpke.NewSender(recipientKey.PublicKey(), kdf, aead, info)
	if err != nil {
		panic(err)
	}
	recipient, err := hpke.NewRecipient(enc, recipientKey, kdf, aead, info)
	if err != nil {
		panic(err)
	}

	// aad 是公开元数据，但会参与认证；编码规则必须在协议中固定。
	aad := []byte("tenant=acme;kind=invoice;seq=0")
	plaintext := []byte("invoice amount: 42")
	ciphertext, err := sender.Seal(aad, plaintext)
	if err != nil {
		panic(err)
	}

	// Open 必须收到完全相同的 aad；任何字段被替换都会导致打开失败。
	decoded, err := recipient.Open(aad, ciphertext)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(decoded))
}

这个示例故意把 aad 写成带字段名的字节串。生产代码不要直接依赖 map 的遍历顺序；应定义稳定的编码格式，例如固定字段顺序、长度前缀或版本化的二进制结构。接收端解析失败和认证失败都应归到同一个对外错误类别，避免借错误信息泄露元数据状态。

aad 不会被加密，但会阻止静默替换

aad 的内容不会出现在密文的保密部分，观察者通常可以看到它；它的价值是让这段公开数据成为认证输入。发送方把“租户 A 的发票”绑定进密文后，攻击者不能只把租户字段改成 B 再把原密文转过去，因为接收方用新的 aad 调用 Open 时，认证标签无法匹配。

这也是我在协议里把这些字段放在一个版本化函数中的原因：

func buildAAD(tenant, kind string, seq uint64) []byte {
	// 固定字段顺序和分隔符，避免发送端与接收端产生不同字节串。
	return []byte(fmt.Sprintf("tenant=%s;kind=%s;seq=%d", tenant, kind, seq))
}

func openMessage(recipient *hpke.Recipient, tenant, kind string, seq uint64, ciphertext []byte) ([]byte, error) {
	// 先用业务字段重建 aad，再交给 HPKE 做认证检查。
	aad := buildAAD(tenant, kind, seq)
	plaintext, err := recipient.Open(aad, ciphertext)
	if err != nil {
		// 对外只返回统一失败，详细原因留在受控日志中。
		return nil, fmt.Errorf("open message: %w", err)
	}
	return plaintext, nil
}

注意 aad 不是签名系统，也不能单独证明“这个租户字段来自可信调用方”。它解决的是密文与公开元数据的一致性；谁有权创建消息、消息是否已经处理过，仍要由密钥权限、认证层和业务状态共同决定。

发送和接收必须共享消息顺序

状态化的 Sender 与 Recipient 都会为成功的调用推进计数器，Go 文档还特别要求接收端的 Open 按发送端 Seal 的相同顺序调用。也就是说，不能把同一个上下文随意分发给多个并发消费者，再期待它自动理解每条消息的独立序号。

如果业务天然允许乱序，通常有三种思路：每条消息建立独立的 HPKE 上下文；在业务层把序号放入 aad 并设计可重建的上下文边界；或者在传输层先恢复顺序再交给同一个 Recipient。单纯把“乱序”当成“换一个 aad”不能解决状态计数器不一致。

把 aad 当成认证绑定，不要当成完整重放防护

我在第一次做消息重试时遇到过一个误区：原消息能被正确打开，就以为攻击者无法再次提交它。实际上，aad 能保证“这条密文对应这些公开字段”，但它不会替业务记录消息是否已经消费。RFC 9180 还强调，HPKE 上下文对丢失消息并不宽容，应用需要检测不可恢复的丢失并丢弃相关上下文。

因此建议至少把下面几项分开设计：

• 完整性：由 aad 和 AEAD 认证保证公开字段未被静默替换。
• 顺序：由同一上下文两端的成功调用顺序和计数器共同保证。
• 重放：由业务侧保存消息 ID、序列号或消费状态来拒绝已经处理过的消息。
• 身份：由密钥分发、认证模式或上层协议确定发送方是谁，不能只靠一串公开 aad。

我的落地清单

对我来说，HPKE 关联数据最实用的落点不是“把更多字段塞进加密 API”，而是把协议约束写成稳定的字节编码。上线前我会逐项确认：

1. info 是否只包含上下文级、两端都会固定的公开信息。
2. aad 是否包含了租户、消息类型、版本和序号等需要绑定的公开字段。
3. 发送端和接收端是否使用同一编码规则，而不是各自拼接字符串。
4. 同一个 Recipient 是否按 Seal 成功顺序调用，丢消息时是否能安全废弃上下文。
5. 认证失败、解析失败、重复消费和无权访问是否有独立的业务处理策略。

如果只是一次性的单条消息，并且不需要关联数据，便捷的 hpke.Seal/Open 更直接；一旦需要逐消息绑定，就切换到 NewSender/NewRecipient，把 aad 当作协议的一部分来版本化和记录。

常见问题

aad 要不要加密？

通常不用。它的角色是公开但不可被静默替换；真正敏感的业务内容仍应放在明文参数里，由 HPKE 加密。

把 tenant 放进 info 可以吗？

只有当一个 HPKE 上下文从头到尾只服务一个固定租户时才合适。若同一上下文承载多个租户消息，租户字段应作为每条消息的 aad。

Open 失败后还能继续使用 Recipient 吗？

不要把失败当成可以随意跳过的普通消息。因为上下文计数器和传输丢失会影响后续状态，应用应按协议判断是否废弃上下文并重新建立。