Go ed25519.Options 怎么启用预哈希签名

排查 Ed25519 签名不兼容时，最容易混淆的是“我已经先做了 SHA-512”与“Go 已经启用 Ed25519ph”并不是一回事。Go 需要通过 ed25519.Options{Hash: crypto.SHA512} 明确选择预哈希变体，而且传给签名和验证函数的消息必须是 SHA-512 摘要。签名端使用 PrivateKey.Sign，验证端使用 VerifyWithOptions，两边的 Hash 和 Context 要保持一致。

预哈希签名真正接收的是什么

Go 的 crypto/ed25519 同时覆盖普通 Ed25519、Ed25519ctx 和 Ed25519ph。预哈希模式的关键不是只在业务层调用一次哈希函数，而是让 Options.Hash 告诉标准库采用 Ed25519ph 规则。官方文档规定：当它是 crypto.SHA512 时，传入的 message 应该已经是 SHA-512 摘要；当它是零值时，才是普通 Ed25519，消息不应预先哈希。

最小配置可以这样写。示例不输出私钥，也不把预哈希摘要误当作普通文本。

package main

import (
    "crypto"
    "crypto/ed25519"
    "crypto/sha512"
    "fmt"
)

func main() {
    // 生成演示用密钥；生产环境应从安全密钥存储读取私钥。
    pub, priv, err := ed25519.GenerateKey(nil)
    if err != nil {
        panic(err)
    }

    message := []byte("order:20261004")
    digest := sha512.Sum512(message)
    opts := &ed25519.Options{
        // SHA512 选择 Ed25519ph，Sign 接收 digest 而不是 message。
        Hash: crypto.SHA512,
        // Context 可用于隔离协议域；签名端和验证端必须完全相同。
        Context: "orders-v1",
    }

    signature, err := priv.Sign(nil, digest[:], opts)
    if err != nil {
        panic(err)
    }
    if err := ed25519.VerifyWithOptions(pub, digest[:], signature, opts); err != nil {
        panic(fmt.Sprintf("signature verification failed: %v", err))
    }
    fmt.Println("Ed25519ph verified")
}

签名和验证必须共享同一组选项

这个问题的故障现场通常表现为：签名生成成功，但另一端验证失败。优先检查的不是密钥长度，而是两端是否都使用了摘要、是否都把 Hash 设为 crypto.SHA512，以及 Context 是否有一个字符不同。Context 为空时表示不额外绑定上下文；非空时最多 255 字节，并会成为签名语义的一部分。

三处边界决定能否互操作

第一，摘要必须由双方对同一份原文计算，传输层只携带摘要时要明确它的算法和编码。第二，不能把 Ed25519ph 生成的签名交给普通 Verify，因为普通接口不知道你选择了哪种变体。第三，Context 不是备注字段；它为空和它为 orders-v1 代表不同的签名域，跨服务协议应把它写进配置或协议文档。

如果调用的是实现了 crypto.Signer 的通用组件，也可以传入 crypto.SHA512 作为 crypto.SignerOpts，但此时仍要遵守 Ed25519ph 的摘要输入约定。为了让代码意图更清晰，直接使用 ed25519.Options 更容易同时表达 Hash 和 Context。

常见问题

已经 sha512.Sum512 了，为什么还要设置 Options.Hash？

摘要只是输入准备；Options.Hash 才选择 Ed25519ph 的签名域。两者缺一不可。

可以把原始消息传给 Hash 为 SHA512 的 Sign 吗？

不应这样做。Ed25519ph 契约要求传入 SHA-512 摘要，原始消息应先计算 sha512.Sum512。

Context 可以在验证端省略吗？

只有签名端使用空 Context 时才可以。非空 Context 必须原样匹配，不能把它当作可选备注。

记住一条排查顺序即可：先确认消息是否为 SHA-512 摘要，再比对 Hash 和 Context，最后确认验证 API 使用的是 VerifyWithOptions。这样能把“算法不一致”和“密钥错误”分开定位。