cryptoHPKE封装会话密钥

Go 的 crypto/hpke 可以把应用生成的一段会话密钥作为明文包装给接收方：发送端用接收公钥调用 Seal，接收端用对应私钥调用 Open。要分清三个对象：应用会话密钥、KEM 产生的封装数据 enc，以及加密后的密文。enc 可以随信封发送，它不是应直接用作应用密钥的明文字节。

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

用户任务：交付一把密钥，而不是传输私钥

设想报表服务要把一次任务的对称密钥交付给指定接收方。我会把调用接口设计成“发送密钥信封”和“打开密钥信封”，而不是让使用者在界面里复制私钥。接收方长期密钥对和本次应用会话密钥承担不同职责，应分别命名。

crypto/hpke 在 Go 1.26 加入标准库。下面按当前官方文档中的 API 编写，目标环境可使用 Go 1.27 系列。示例固定 DHKEM(X25519)、HKDF-SHA256 和 AES-256-GCM，演示一个 32 字节应用密钥的包装；不把它扩展为完整的身份认证或双向会话协议。

交互拆解：公钥材料、信封和本地秘密

发送端需要可信的接收公钥、约定好的算法套件与 info。接收端保留私钥，使用相同约定打开信封。info 是公开的上下文信息，可用于区分协议用途；它不是口令，也不应承担保密功能。

单次函数 hpke.Seal 返回的是 enc 与实际密文的拼接。单次 hpke.Open 接受这份组合数据，因此应用不必自行猜测并切分 enc 的长度。若改用 NewSender 和 NewRecipient，上层协议才需要分别保存 enc 与后续消息密文，两套接口的输入形状不能混用。

组件实现：用单次 Seal 和 Open 包装密钥

下面的独立程序在一个进程内模拟双方，不连接网络，不读取真实凭据。公钥经过序列化再解析，密钥信封则保持为字节切片。实际传输时可采用协议明确规定的编码，接收方解码后再调用 Open。

package main

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

func demo() error {
    // 固定示例套件，双方必须使用相同的 KEM、KDF 和 AEAD。
    kem := hpke.DHKEM(ecdh.X25519())
    kdf, aead := hpke.HKDFSHA256(), hpke.AES256GCM()
    recipientKey, err := kem.GenerateKey()
    if err != nil {
        return fmt.Errorf("生成接收密钥：%w", err)
    }

    // 示例在同一进程模拟公钥交付；实际系统需认证公钥来源。
    publicBytes := recipientKey.PublicKey().Bytes()
    publicKey, err := kem.NewPublicKey(publicBytes)
    if err != nil {
        return fmt.Errorf("读取接收公钥：%w", err)
    }

    // 这 32 字节是应用自己生成的会话密钥，不是 enc。
    sessionKey := make([]byte, 32)
    if _, err := rand.Read(sessionKey); err != nil {
        return fmt.Errorf("生成会话密钥：%w", err)
    }
    info := []byte("report-key-envelope/v1")
    wrapped, err := hpke.Seal(publicKey, kdf, aead, info, sessionKey)
    if err != nil {
        return fmt.Errorf("包装会话密钥：%w", err)
    }

    // wrapped 已包含 enc 和密文，直接交给对应的单次 Open。
    recovered, err := hpke.Open(recipientKey, kdf, aead, info, wrapped)
    if err != nil {
        return fmt.Errorf("打开密钥信封：%w", err)
    }
    if len(recovered) != 32 {
        return fmt.Errorf("恢复密钥长度不符合应用约定")
    }
    // 只比较往返语义，不打印密钥；生产接收端没有原密钥可比较。
    if !bytes.Equal(sessionKey, recovered) {
        return fmt.Errorf("示例往返内容不一致")
    }
    fmt.Println("会话密钥信封已恢复")
    return nil
}

func main() {
    if err := demo(); err != nil {
        fmt.Println("处理失败：", err)
    }
}

从代码语义看，双方套件、info 和密钥匹配时，预期打印“会话密钥信封已恢复”。这是预期行为说明，不是本机运行记录。程序只打印状态，不打印应用密钥或接收私钥。

32 字节是此示例的应用约定，不是 HPKE 只能处理 32 字节。bytes.Equal 仅用于同进程演示往返是否一致，不应被当成生产身份认证或额外密钥确认机制。

可访问性：让字段含义和失败状态容易辨认

对外的接口说明应明确写出“接收公钥”“密钥标识”“算法套件”“密钥信封”，避免把它们都叫 key。界面应为每个字段提供文字标签，成功和失败状态也用明确文字表达，不能只靠绿色与红色区分。二进制信封编码应标注格式，减少误把编码后的字符串直接传给 Open 的情况。

Open 返回错误时，接收端不能把输出当作可用会话密钥继续执行任务。对使用者可显示统一的“无法打开密钥信封”；内部日志可以记录阶段和请求标识，但不记录私钥、恢复出的密钥或完整敏感内容。输入长度上限与请求配额由应用入口负责。

性能检查：先选一次性包装还是状态上下文

每个独立任务只交付一把应用密钥时，单次函数的边界比较清楚。若同一 HPKE 上下文需要承载多条消息，可研究 Sender 与 Recipient 的状态接口；它们维护计数器，接收端 Open 必须与发送端 Seal 保持消息顺序，不能当作任意无序任务共享的无状态对象。

如果业务目标是让双方从同一 HPKE 上下文派生应用秘密，可以使用 Export，并约定相同 exporterContext 和长度。这与“把已经存在的会话密钥作为明文包装”是不同任务。不要把 Export 结果与 enc 混为一谈，也不要认为额外派生接口会自动完成应用认证。

这里不给出吞吐量数字。套件、公钥尺寸、上下文创建次数和应用的请求并发都会影响成本，应针对实际消息模型另行测量，不能把一次能解密当成性能结论。

边界状态：能解密不等于可信发送者

本例持有接收公钥的任何一方都能构造信封，因此它不证明发送者身份。公钥本身需要可信绑定，谁有权发起任务也需要应用的认证和授权。攻击者替换公钥的风险不能靠“已经使用加密”这一点消除。

一次性信封还需要应用层重放策略，例如给任务分配唯一标识，并把标识纳入双方约定的上下文，同时在接收端记录已处理任务。只有标识、没有服务端状态，并不能阻止整份信封被重复提交。接收私钥泄露后的历史保密也不能凭此示例得到保证。

能只发送 enc 吗？对于本文包装已有应用密钥的方案不够，还必须交付对应密文；单次 Seal 已将二者组合。

info 能保密吗？不能，应把它视为公开约定。需要保密的数据放在加密明文中。

需要自己实现 KEM 或拼装密码算法吗？此示例直接使用标准库套件与接口，不自行实现密码原语。

参考：Go crypto/hpke 文档；Go 1.26 发布说明；RFC 9180。