Go crypto/hpke 怎样用封装密钥加密短消息

用 Go 的 crypto/hpke 加密一段短消息，最直接的路径是：接收方生成 HPKE 私钥并公开公钥，发送方用公钥调用 Seal，接收方再用私钥调用 Open。Seal 返回的不是只有 AEAD 密文，而是“封装密钥 + 密文”的组合载荷；这段载荷要整体交给 Open。

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

先固定 HPKE 套件和消息边界

HPKE 可以拆成三个密码组件：KEM 负责用接收方公钥建立共享秘密，KDF 负责从共享秘密派生会话密钥，AEAD 负责对短消息做认证加密。Go 官方包把这三个选择分别暴露为 KEM、KDF 和 AEAD 接口。

为了让示例的代码和数据边界清楚，本文固定使用 X25519、HKDF-SHA256 和 AES-256-GCM。info 不是密码，也不是要保密的消息；它是参与 HPKE 上下文绑定的公开字节串，发送方与接收方必须约定相同内容。

生成接收方密钥并交换公钥

先站在接收方一侧生成密钥对。私钥只保留在接收方；发送方只需要得到 PublicKey().Bytes() 序列化后的公钥字节。公钥在传输中被解析为 hpke.PublicKey 后，才能交给一次性 Seal 接口。

package main

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

func main() {
    // 选定一个 KEM；X25519 的 KDF 组合由 hpke.DHKEM 根据曲线确定。
    kem := hpke.DHKEM(ecdh.X25519())

    // 接收方生成私钥，并从私钥导出可公开传输的公钥。
    recipientPrivateKey, err := kem.GenerateKey()
    if err != nil {
        panic(err)
    }
    publicKeyBytes := recipientPrivateKey.PublicKey().Bytes()

    // 发送方收到公钥字节后，按同一个 KEM 解析；这里只演示解析边界。
    recipientPublicKey, err := kem.NewPublicKey(publicKeyBytes)
    if err != nil {
        panic(err)
    }
    fmt.Println(recipientPublicKey.KEM().ID())
}

真实应用中，recipientPrivateKey 应由接收方的密钥管理边界持有，不能随消息一起传给发送方。公钥序列化格式由 KEM 实现定义，接收方读取到公钥时也应把解析错误当作输入错误处理，而不是继续尝试加密。

调用 Seal 生成封装密钥与密文

Seal 是适合“一次加密一条短消息”的便捷函数。它内部创建发送上下文，然后返回封装密钥和 AEAD 密文的拼接结果。这个设计让发送方不需要保存一个可长期复用的发送上下文，但也意味着每次调用都要把返回值当作完整载荷保存和传输。

// senderSeal 使用接收方公钥把一条短消息封装为可传输载荷。
func senderSeal(publicKey hpke.PublicKey, plaintext []byte) ([]byte, error) {
    // 三个组件必须和接收方 Open 使用的配置一致。
    kdf := hpke.HKDFSHA256()
    aead := hpke.AES256GCM()

    // info 用来绑定应用上下文；双方约定后必须保持字节内容完全一致。
    info := []byte("17golang/hpke-short-message-v1")

    // Seal 返回 enc||ciphertext：前部是封装密钥，后部是认证密文。
    return hpke.Seal(publicKey, kdf, aead, info, plaintext)
}

这里没有额外的 AAD 参数，因为顶层 Seal 是无 AAD 的一次性便捷接口。如果协议需要把消息头、租户标识或版本字段作为附加认证数据，应改用 NewSender 创建发送上下文，再调用 Sender.Seal(aad, plaintext)；不要把 AAD 直接拼到明文里后假设它具有同样的认证语义。

调用 Open 恢复短消息

接收方拿到完整的 enc||ciphertext 后，使用自己的私钥、同一个 KDF、AEAD 和 info 调用 Open。下面把生成密钥、封装和解封放在一个完整示例里，便于看清两端真正共享的只有公钥、套件选择和 info。

package main

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

func main() {
    // 双方先固定同一套 KEM、KDF 和 AEAD。
    kem := hpke.DHKEM(ecdh.X25519())
    kdf := hpke.HKDFSHA256()
    aead := hpke.AES256GCM()
    info := []byte("17golang/hpke-short-message-v1")

    // 接收方保留私钥，只把对应的公钥交给发送方。
    recipientPrivateKey, err := kem.GenerateKey()
    if err != nil {
        panic(err)
    }
    recipientPublicKey := recipientPrivateKey.PublicKey()

    // 发送方用接收方公钥封装短消息，返回值必须整体保存。
    plaintext := []byte("hello from HPKE")
    ciphertext, err := hpke.Seal(recipientPublicKey, kdf, aead, info, plaintext)
    if err != nil {
        panic(err)
    }

    // 接收方用私钥解封；认证失败、参数不匹配或载荷损坏都会返回错误。
    recovered, err := hpke.Open(recipientPrivateKey, kdf, aead, info, ciphertext)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(recovered))
}

这个例子的重点不是把结果打印出来，而是确认数据契约：发送方传的是 Seal 的完整返回值，接收方把它原样交给 Open。如果业务协议还要携带消息编号、版本或路由字段，应在外层定义明确的消息格式，避免依赖“猜一个切片位置”来拆分 HPKE 载荷。

按应用边界封装和排错

一次性接口适合短消息和简单调用。如果同一发送方要在一个 HPKE 会话中连续加密多条消息，可以使用 NewSender 得到 enc 与 *Sender，并多次调用 Sender.Seal；接收方则用 NewRecipient 结合封装密钥创建接收上下文，再调用 Recipient.Open。这时封装密钥与后续消息的组织方式属于你的应用协议，不能与顶层 Seal 的返回格式混用。

还要区分“封装密钥”与“接收方私钥”：封装密钥属于某次发送载荷的一部分，可以随密文传递；接收方私钥是长期敏感材料，不应放入消息正文、日志或客户端可读字段。本文示例只覆盖加密接口调用，不替代密钥轮换、存储、身份认证和消息重放防护设计。

常见问题

为什么不能只把 Seal 返回值的后半段交给 Open？

因为顶层 Open 需要从完整输入中读取封装密钥，再用接收方私钥恢复共享密钥。缺少前部的 enc，接收方无法建立解封上下文。

info 可以留空吗？

可以把它设为空字节串，但只要使用了非空 info，双方就必须保持完全一致。工程上通常用它绑定协议名、用途或版本，避免不同上下文误用同一把派生密钥。

Seal 能直接加密很大的文件吗？

它更适合一次性的短消息。大文件通常需要外层设计分块、流式 AEAD、封装密钥复用和失败恢复；不要仅因为函数接受 []byte 就把所有数据一次性读入内存。

Open 出错时可以忽略并继续使用部分明文吗？

不可以。认证失败时应丢弃返回数据并记录可操作的错误上下文，不能把不完整或未认证的结果交给业务层。