Go ed25519.VerifyWithOptions 何时返回错误而不是 false

ed25519.VerifyWithOptions 不会返回 false，因为它的返回类型就是 error。签名有效时返回 nil；签名无效、签名长度不对、选项不受支持，或者 Ed25519ph/Ed25519ctx 的参数不符合约束时返回非 nil 错误。只有较简单的 ed25519.Verify 才用 true 和 false 表示验签结果。

Go 标准库文档：https://pkg.go.dev/crypto/ed25519

一、VerifyWithOptions 不会返回 false

两个接口解决的基础任务相同，但返回模型不同。Verify(publicKey, message, sig) 适合纯 Ed25519，调用结果可以直接写成 if !ed25519.Verify(...) { ... }。需要 Ed25519ph 或 Ed25519ctx 时，改用 VerifyWithOptions，并把 err == nil 当作唯一成功条件。

二、最小可用写法：统一检查 error

普通 Ed25519 也可以使用 VerifyWithOptions，只要 Hash 为零且 Context 为空。对外部输入，建议先检查固定长度，再进入标准库验签；这样能把公钥长度导致的 panic 收口成调用方可处理的错误。

package signature

import (
	"crypto/ed25519"
	"fmt"
)

func VerifyPlain(pub ed25519.PublicKey, message, sig []byte) error {
	// 标准库遇到错误公钥长度会 panic，先在不可信输入边界拦截。
	if len(pub) != ed25519.PublicKeySize {
		return fmt.Errorf("公钥长度应为 %d 字节，实际为 %d", ed25519.PublicKeySize, len(pub))
	}
	if len(sig) != ed25519.SignatureSize {
		return fmt.Errorf("签名长度应为 %d 字节，实际为 %d", ed25519.SignatureSize, len(sig))
	}

	// 空 Options 选择普通 Ed25519；nil 表示有效，非 nil 表示拒绝。
	return ed25519.VerifyWithOptions(pub, message, sig, &ed25519.Options{})
}

调用处不需要再判断真假：

if err := VerifyPlain(pub, payload, signature); err != nil {
	// 对外统一报告验签失败，内部日志不要记录消息、签名或密钥材料。
	return fmt.Errorf("请求签名校验失败: %w", err)
}
// 只有 err 为 nil 时，才继续处理已经通过认证的 payload。
return handleAuthenticated(payload)

三、哪些情况会得到非 nil error

非 nil error 不只对应“签名内容被篡改”。VerifyWithOptions 同时承担变体选择和参数检查，因此错误大致分为两类：一类是签名本身无效，另一类是调用参数无法构成合法的 Ed25519 变体验证。

普通 Ed25519 要传原始消息，不能先做 SHA-512 再把摘要当消息传入。只有 Options.Hash 明确设为 crypto.SHA512 时才选择 Ed25519ph，而且这时 message 参数应当是 64 字节摘要。

func VerifyPrehashed(pub ed25519.PublicKey, digest, sig []byte, context string) error {
	// Ed25519ph 接收 SHA-512 摘要，不接收任意长度的原始消息。
	if len(digest) != sha512.Size {
		return fmt.Errorf("SHA-512 摘要长度应为 %d 字节", sha512.Size)
	}
	if len(context) > 255 {
		return fmt.Errorf("Ed25519 上下文不能超过 255 字节")
	}

	// Hash=SHA512 选择 Ed25519ph；签名端必须使用相同 context。
	return ed25519.VerifyWithOptions(pub, digest, sig, &ed25519.Options{
		Hash:    crypto.SHA512,
		Context: context,
	})
}

四、哪些异常不会作为普通 error 返回

官方契约明确写明：公钥长度不等于 ed25519.PublicKeySize 时，VerifyWithOptions 会 panic。这属于调用前置条件，不应让来自网络、文件或数据库的未校验字节直接触发。对外部公钥先检查长度，或在协议解析阶段构造受控的公钥对象。

opts 也应始终传入有效的 &ed25519.Options{}。不要把 nil 当作“默认选项”；函数需要读取其中的 Hash 和 Context。同样，不要依赖错误字符串来区分业务分支，因为这些错误没有公开的稳定哨兵值。

五、规模化验签服务怎么收口返回语义

在只有一个调用点的小程序里，直接检查 error 足够。服务增多后，旧架构常见的问题是：有的模块调用 Verify 并返回 bool，有的模块调用 VerifyWithOptions 并返回 error，还有的模块把所有 error 都统计为服务器故障。最终同一次无效签名会被记成不同指标。

更稳妥的做法是建立一层验签适配器：协议层先检查公钥和签名长度，配置层固定算法变体、Hash 和 Context，密码层只调用标准库，业务层再把非 nil error 映射为“认证拒绝”。结构或配置错误可以单独计入内部指标，但对外响应不必暴露是长度、上下文还是数学验证失败，避免把过多验证细节变成探测信号。

这种收口会增加一个适配层和少量配置管理成本，却能让所有调用方共享同一返回模型。上线后应重点观察无效签名比例、结构错误比例和配置错误比例，而不是把每个非 nil error 都算作服务异常。

相关问题

VerifyWithOptions 返回 nil 就一定是普通 Ed25519 吗？

不一定。返回 nil 只说明按给定 Options 选择的变体验证成功；Hash 和 Context 可能选择的是 Ed25519ph 或 Ed25519ctx。

可以用 errors.Is 区分“签名无效”和“选项错误”吗？

标准库没有为这些结果公开可匹配的哨兵错误。若业务确实要分类，应在调用前对长度、Hash、Context 和摘要长度做结构检查；验签返回的其他非 nil error 统一按签名拒绝处理。

为什么 Verify 使用 false，而 VerifyWithOptions 使用 error？

Verify 只有普通 Ed25519 的单一验证路径；VerifyWithOptions 还要表达变体选择与参数约束失败，因此 error 能携带比布尔值更多的失败信息。

参考：https://pkg.go.dev/crypto/ed25519。文档对两个接口的返回类型、Ed25519ph 的 SHA-512 摘要要求、Context 长度限制和公钥长度 panic 边界有直接说明。