Go crypto/mlkem 怎样区分公钥封装和解封装

在 Go 的 crypto/mlkem 里，“公钥封装”和“私钥解封装”不是同一个对象上的两种随意叫法，而是由两类密钥和两条方法明确分工：发送方拿接收方的 EncapsulationKey 调用 Encapsulate，得到共享密钥与密文；接收方保留自己的 DecapsulationKey，调用 Decapsulate 从密文恢复共享密钥。

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

记忆方法很简单：公钥对象负责“封装并产生密文”，私钥对象负责“解封装并恢复密钥”。EncapsulationKey 可以发送，DecapsulationKey 必须保密；两端最终比较的是共享密钥，而不是比较两份密钥对象。

先看清 crypto/mlkem 的两类密钥

Go 1.24 将 ML-KEM-768 和 ML-KEM-1024 放进标准库。常规场景可以先选择 ML-KEM-768：接收方调用 GenerateKey768 生成 DecapsulationKey768，再通过 EncapsulationKey 方法导出对应的公钥对象。这个导出动作不会把私钥变成可公开的字节串，而是得到专门用于产生密文的公钥材料。

公钥封装：EncapsulationKey 调用 Encapsulate

公钥封装发生在发送方。发送方拿到接收方提供的公钥字节后，用 NewEncapsulationKey768 解析；解析成功后，Encapsulate 返回两个结果：共享密钥和要发回接收方的密文。这里的“封装”不是对业务明文直接加密，而是为后续对称加密准备一份双方都能得到的共享密钥。

package main

import (
	"crypto/mlkem"
	"fmt"
)

// encapsulateOnSender 模拟发送方只持有接收方公开的封装公钥。
func encapsulateOnSender(publicBytes []byte) ([]byte, []byte, error) {
	// 解析公钥字节；长度或编码不正确时在这里返回错误。
	ek, err := mlkem.NewEncapsulationKey768(publicBytes)
	if err != nil {
		return nil, nil, fmt.Errorf("解析封装公钥: %w", err)
	}

	// 封装会随机生成共享密钥，并生成需要传给接收方的密文。
	sharedKey, ciphertext := ek.Encapsulate()
	return sharedKey, ciphertext, nil
}

看到 NewEncapsulationKey768 和 Encapsulate，基本就可以判断这是公钥侧。公钥对象的 Bytes 可以序列化后传输；共享密钥和密文则要按协议分别处理，不能把密文误当成共享密钥。

私钥解封装：DecapsulationKey 调用 Decapsulate

接收方不需要重新解析公钥，也不应该把私钥发给发送方。它保留生成时得到的 DecapsulationKey768，把发送方返回的密文交给 Decapsulate。成功后得到的共享密钥应与发送方的共享密钥一致，随后再交给双方约定的对称加密或密钥派生流程。

package main

import (
	"crypto/mlkem"
	"fmt"
)

// decapsulateOnReceiver 模拟接收方使用未离开本地的私钥恢复共享密钥。
func decapsulateOnReceiver(dk *mlkem.DecapsulationKey768, ciphertext []byte) ([]byte, error) {
	// 密文长度错误会返回 error；共享密钥本身不能写入日志或发送到网络。
	sharedKey, err := dk.Decapsulate(ciphertext)
	if err != nil {
		return nil, fmt.Errorf("解封装密文: %w", err)
	}
	return sharedKey, nil
}

看到 DecapsulationKey768 和 Decapsulate，就是私钥侧。DecapsulationKey 的字节表示是种子形式，文档明确要求保密；文章中的示例只传递公钥字节和密文，不传递私钥。

一段完整的角色对照

下面把两端动作放在同一段代码中，重点看变量的生命周期：dk 只留在接收方，publicBytes 可以发送，ciphertext 需要回传，两个 sharedKey 应该一致。

package main

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

func main() {
	// 接收方生成并保留解封装私钥，只公开对应的封装公钥。
	dk, err := mlkem.GenerateKey768()
	if err != nil {
		panic(err)
	}
	publicBytes := dk.EncapsulationKey().Bytes()

	// 发送方用公钥封装，得到发送回接收方的密文和本地共享密钥。
	ek, err := mlkem.NewEncapsulationKey768(publicBytes)
	if err != nil {
		panic(err)
	}
	senderKey, ciphertext := ek.Encapsulate()

	// 接收方用私钥解封装同一份密文，恢复另一份共享密钥。
	receiverKey, err := dk.Decapsulate(ciphertext)
	if err != nil {
		panic(err)
	}

	// 只比较结果是否一致；生产代码不要输出共享密钥内容。
	same := subtle.ConstantTimeCompare(senderKey, receiverKey) == 1
	fmt.Println("shared key matches:", same)
}

这段代码的关键不是把 ML-KEM 当成通用数据加密器，而是完成一次密钥封装机制：发送方生成共享密钥并携带密文，接收方使用私钥恢复共享密钥。业务数据通常还需要使用共享密钥驱动的对称加密方案，具体协议不能省略认证和密钥生命周期设计。

返回值怎样判断：错误不等于密钥一定匹配

Decapsulate 对密文长度有明确检查：长度不正确会返回错误。需要特别注意的是，长度正确但内容无效的密文，按照 ML-KEM 的规范可能不会返回错误，而是产生一份与发送方不匹配的共享密钥。因此调用方不能只把“没有 error”当成业务消息已经可信。

迁移时的两个边界

第一，ML-KEM-768 和 ML-KEM-1024 的类型、构造函数和长度常量成套对应，不能把一种参数集的公钥或密文交给另一种参数集的对象。第二，较新的 Go 文档还提供了 DecapsulationKey768.Encapsulator 等抽象接口入口；如果项目需要面向 crypto.Encapsulator 编程，应确认项目工具链满足该方法标注的版本要求。只为完成基本封装时，直接使用具体的 EncapsulationKey768 与 DecapsulationKey768 更容易读懂。

最小判断清单

• 要公开给对方的是 dk.EncapsulationKey().Bytes()，不是 dk.Bytes()。
• 发送方看到 NewEncapsulationKey768 后调用 Encapsulate。
• 接收方保留 DecapsulationKey768，对收到的密文调用 Decapsulate。
• 比较双方得到的共享密钥，不比较公钥字节和密文字节是否相等。
• 对合法长度但无效内容的密文，不把“无 error”直接等同于业务层可信。

常见问题

公钥封装是不是把明文加密后返回？

不是。Encapsulate 生成共享密钥和密文，业务明文还要由后续对称加密协议处理。

为什么解封装没有报错但两边密钥不一样？

如果密文长度正确但内容无效，ML-KEM 可以返回不匹配的共享密钥而不返回错误；调用方需要把共享密钥放进完整的协议流程中，并做好消息认证。

可以只保存公钥，稍后再解封装吗？

不可以。解封装需要对应的 DecapsulationKey，公钥只能用于封装，不能替代接收方私钥。