Go 1.27 新增 crypto/hpke 解决什么密钥封装需求

如果你在 Go 1.27 项目里看到 crypto/hpke，先纠正一个容易混淆的版本点：它并不是 Go 1.27 才首次出现，而是 Go 1.26 发布说明中加入的标准库包；Go 1.27 环境可以继续直接使用。它解决的核心需求也不是“把大文件交给一个神奇 API 加密”，而是让发送方用接收方公钥封装出一次会话秘密，再用 AEAD 保护消息。

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

HPKE 适合“我只拿到对方公钥，但要安全发送一条消息或建立一个加密上下文”的场景。crypto/hpke 把 KEM、KDF 和 AEAD 组合成 RFC 9180 定义的接口，减少手写密钥协商、派生和密文格式时的拼接错误。

Go 1.27 与 crypto/hpke 的关系要先分清

Go 1.27 的发布说明列出了不少标准库变化，但 crypto/hpke 的首次引入应以 Go 1.26 发布说明为准。这个校正很重要：如果项目的最低版本是 Go 1.26，就可以按包文档评估；如果正在升级到 Go 1.27，则重点是确认构建链、FIPS 模式、密钥存储和协议格式，而不是把它当成全新的加密算法。

HPKE 是 RFC 9180 定义的组合式方案。发送方拿到接收方公钥后，KEM 产生封装结果和共享秘密，KDF 将共享秘密派生成会话密钥，AEAD 再用这个密钥保护明文。接收方用私钥解封装，得到同一会话密钥。封装结果会随密文传输，但私钥不会离开接收方。

它解决的是密钥封装，不是替代所有文件加密

传统做法常把 ECDH、哈希、随机数、AEAD 和自定义序列化格式拼在一起：每个组件单看都可能正确，但组合时容易遗漏 info、AAD、nonce 或密钥轮换边界。HPKE 先把组合模型固定下来，再让应用选择 KEM、KDF 和 AEAD。

因此它更适合密钥配送、短消息保护、令牌包装、协议握手后的加密上下文，以及需要把传统密钥交换与后量子混合方案放进同一接口的场景。大文件仍应使用专门的流式或分块加密设计，再用 HPKE 保护数据密钥；不要把整个文件一次性放进单次 Seal。

用 Seal 和 Open 完成一次最小封装

下面的示例选择后量子混合 KEM、HKDF-SHA256 和 AES-256-GCM。它展示的是单次消息路径：接收方先生成私钥并公布公钥，发送方根据公钥调用 Seal，接收方再调用 Open。真实协议还要把套件标识、info、版本和密文长度写入明确的消息格式。

package main

import (
    "fmt"
    "log"

    "crypto/hpke"
)

func main() {
    // 选择后量子混合 KEM、HKDF-SHA256 和 AES-256-GCM 作为示例套件。
    kem, kdf, aead := hpke.MLKEM768X25519(), hpke.HKDFSHA256(), hpke.AES256GCM()

    // 接收方生成私钥，并把公钥安全地交给发送方。
    recipientPrivateKey, err := kem.GenerateKey()
    if err != nil {
        log.Fatal(err)
    }
    recipientPublicKey := recipientPrivateKey.PublicKey()

    // info 要固定在协议定义中；它用于区分不同业务上下文。
    info := []byte("order-message-v1")
    plaintext := []byte("订单密钥只在接收方解封装")

    // Seal 返回封装结果与密文的拼接字节，发送方不需要接触接收方私钥。
    sealed, err := hpke.Seal(recipientPublicKey, kdf, aead, info, plaintext)
    if err != nil {
        log.Fatal(err)
    }

    // Open 会从 sealed 中读取封装结果，再用私钥恢复并解密明文。
    recovered, err := hpke.Open(recipientPrivateKey, kdf, aead, info, sealed)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(recovered))
}

示例里最容易被忽略的是 info：发送方和接收方必须按协议约定使用同一值，否则会得到不同上下文，解封装自然失败。sealed 也不是只有 AEAD 密文，它还包含接收方恢复共享秘密所需的封装部分，传输层应把它当作不透明字节处理。

多条消息要换成 Sender/Recipient 上下文

如果一个连接要连续保护多条消息，可以使用 NewSender 和 NewRecipient 建立上下文，再对每条消息调用 Sender.Seal 或 Recipient.Open。这种方式更适合把 AAD、序号、会话生命周期和错误处理放进协议设计，而不是每条消息都重新拼一次单次 API。

还要注意三条边界：第一，公钥来源必须有身份认证，否则 HPKE 只能保证“对某个公钥加密”，不能保证这个公钥确实属于目标接收方；第二，AAD 虽不加密，却会参与认证，读取时必须原样提供；第三，套件和格式不要隐式漂移，升级 KEM 或 AEAD 时应增加版本并保留解码策略。

Go crypto/hpke 常见问题

crypto/hpke 是 Go 1.27 才新增的吗？

不是。官方 Go 1.26 发布说明已经列出新的 crypto/hpke 包；Go 1.27 可以继续使用它。文章标题沿用批次冻结标题，版本事实应以对应发布说明为准。

HPKE 会自动帮我验证公钥身份吗？

不会。它负责封装与认证加密，但公钥分发、证书校验、密钥指纹或账号绑定仍属于应用协议。

为什么不直接用 AES-GCM？

AES-GCM 需要共享对称密钥；HPKE 解决的是“发送方只有接收方公钥”的密钥建立与封装问题，二者承担的层次不同。

可以把一段超大文件直接传给 Seal 吗？

不建议。大文件应采用分块或流式 AEAD，HPKE 更适合作为数据密钥的封装层，并由协议定义块序号和失败恢复。

采用前先确认 Go 版本、FIPS 或合规要求、KEM 套件支持、密钥身份来源和消息格式。对短消息先用 Seal/Open 理清封装边界，对会话和文件则把上下文、分块与轮换设计写进协议，而不是只替换一个 import。