271 lines
11 KiB
Go
271 lines
11 KiB
Go
// Package ed25519x 基于标准库 crypto/ed25519 提供 Ed25519 数字签名的
|
||
// 密钥生成、PEM 编解码、签名与验签能力。
|
||
//
|
||
// 安全说明：
|
||
// - Ed25519 是确定性签名算法，不使用随机数，因此不存在 ECDSA 中"随机
|
||
// nonce 重复导致私钥泄露"的风险，也不需要调用方选择曲线或哈希算法。
|
||
// 它是新系统的推荐默认签名算法。
|
||
// - 私钥固定为 64 字节（32 字节种子 || 32 字节公钥）。私钥泄露等同于身份
|
||
// 被完全冒充，请仅存放在可信位置；本包不会把私钥写入日志或错误信息，
|
||
// 也不提供自动清零，调用方使用完毕后应自行零覆盖相关内存。
|
||
// - 本包只做签名/验签，不提供加密与密钥协商；Ed25519 的签名结果不能当作
|
||
// 对称密钥或随机数使用。
|
||
// - 签名只保证完整性与来源真实性，不提供保密性：消息本身仍可能被读取。
|
||
package ed25519x
|
||
|
||
import (
|
||
"crypto/ed25519"
|
||
"crypto/rand"
|
||
"crypto/x509"
|
||
"encoding/base64"
|
||
"encoding/pem"
|
||
"errors"
|
||
"fmt"
|
||
"os"
|
||
)
|
||
|
||
const (
|
||
// PublicKeySize Ed25519 公钥的固定字节长度（32）。
|
||
PublicKeySize = ed25519.PublicKeySize
|
||
// PrivateKeySize Ed25519 私钥的固定字节长度（64，即 32 字节种子加 32 字节公钥）。
|
||
PrivateKeySize = ed25519.PrivateKeySize
|
||
// SignatureSize Ed25519 签名的固定字节长度（64）。
|
||
SignatureSize = ed25519.SignatureSize
|
||
)
|
||
|
||
// PEM 块类型标签，解析时严格校验，避免把别的算法或别的对象当成密钥使用。
|
||
const (
|
||
pemTypePrivateKey = "PRIVATE KEY"
|
||
pemTypePublicKey = "PUBLIC KEY"
|
||
)
|
||
|
||
// 文件权限：私钥仅所有者可读写，公钥可被其他用户读取。
|
||
const (
|
||
privateFileMode os.FileMode = 0o600
|
||
publicFileMode os.FileMode = 0o644
|
||
)
|
||
|
||
// GenerateKey 生成一对新的 Ed25519 密钥。
|
||
//
|
||
// 返回值均为原始字节，长度分别恒为 PublicKeySize 与 PrivateKeySize；
|
||
// privateKey 是敏感材料，不要打印到日志、不要经网络发送，也不要以明文落盘。
|
||
//
|
||
// 返回的 publicKey 与 privateKey[32:] 相同，调用方只需保存 privateKey
|
||
// 即可，但本包不做裁剪，保持与标准库一致的 64 字节形态。
|
||
func GenerateKey() (publicKey, privateKey []byte, err error) {
|
||
pub, priv, err := ed25519.GenerateKey(rand.Reader)
|
||
if err != nil {
|
||
return nil, nil, fmt.Errorf("生成 Ed25519 密钥失败: %w", err)
|
||
}
|
||
return []byte(pub), []byte(priv), nil
|
||
}
|
||
|
||
// GenerateKeyPEM 生成一对新的 Ed25519 密钥并以 PEM 文本返回。
|
||
//
|
||
// privatePEM 为 PKCS#8 编码（块类型 "PRIVATE KEY"），publicPEM 为 PKIX
|
||
// 编码（块类型 "PUBLIC KEY"），二者可直接写入 .pem 文件。
|
||
//
|
||
// 安全提醒：privatePEM 是明文私钥，落盘时必须使用 0600 之类的严格权限
|
||
// （可参考 SaveKeyPair），不要把私钥 PEM 提交到版本库或打进镜像层。
|
||
func GenerateKeyPEM() (privatePEM, publicPEM []byte, err error) {
|
||
pub, priv, err := ed25519.GenerateKey(rand.Reader)
|
||
if err != nil {
|
||
return nil, nil, fmt.Errorf("生成 Ed25519 密钥失败: %w", err)
|
||
}
|
||
privatePEM, err = MarshalPrivateKeyPEM(priv)
|
||
if err != nil {
|
||
return nil, nil, err
|
||
}
|
||
publicPEM, err = MarshalPublicKeyPEM(pub)
|
||
if err != nil {
|
||
return nil, nil, err
|
||
}
|
||
return privatePEM, publicPEM, nil
|
||
}
|
||
|
||
// MarshalPrivateKeyPEM 把 Ed25519 私钥编码为 PKCS#8 的 PEM 文本。
|
||
//
|
||
// 私钥长度不是 PrivateKeySize 时返回错误，不会 panic。
|
||
// 返回值是未加密的明文私钥，请按私钥要求保护。
|
||
func MarshalPrivateKeyPEM(priv ed25519.PrivateKey) ([]byte, error) {
|
||
if len(priv) != PrivateKeySize {
|
||
return nil, fmt.Errorf("Ed25519 私钥长度非法: 期望 %d 字节, 实际 %d 字节", PrivateKeySize, len(priv))
|
||
}
|
||
der, err := x509.MarshalPKCS8PrivateKey(priv)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("PKCS#8 编码 Ed25519 私钥失败: %w", err)
|
||
}
|
||
return pem.EncodeToMemory(&pem.Block{Type: pemTypePrivateKey, Bytes: der}), nil
|
||
}
|
||
|
||
// MarshalPublicKeyPEM 把 Ed25519 公钥编码为 PKIX 的 PEM 文本。
|
||
//
|
||
// 公钥长度不是 PublicKeySize 时返回错误，不会 panic。
|
||
func MarshalPublicKeyPEM(pub ed25519.PublicKey) ([]byte, error) {
|
||
if len(pub) != PublicKeySize {
|
||
return nil, fmt.Errorf("Ed25519 公钥长度非法: 期望 %d 字节, 实际 %d 字节", PublicKeySize, len(pub))
|
||
}
|
||
der, err := x509.MarshalPKIXPublicKey(pub)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("PKIX 编码 Ed25519 公钥失败: %w", err)
|
||
}
|
||
return pem.EncodeToMemory(&pem.Block{Type: pemTypePublicKey, Bytes: der}), nil
|
||
}
|
||
|
||
// ParsePrivateKeyPEM 解析 PKCS#8 的 Ed25519 私钥 PEM。
|
||
//
|
||
// 只接受块类型为 "PRIVATE KEY" 的 PEM；块缺失、DER 非法、长度不符，或内容
|
||
// 是 RSA/ECDSA 等其他算法时均返回错误（错误文本只包含类型与长度，不含密钥材料）。
|
||
// 加密的 PKCS#8（"ENCRYPTED PRIVATE KEY"）不被支持。
|
||
func ParsePrivateKeyPEM(data []byte) (ed25519.PrivateKey, error) {
|
||
block, _ := pem.Decode(data)
|
||
if block == nil {
|
||
return nil, errors.New("解析 Ed25519 私钥 PEM 失败: 数据不是合法的 PEM")
|
||
}
|
||
if block.Type != pemTypePrivateKey {
|
||
return nil, fmt.Errorf("解析 Ed25519 私钥 PEM 失败: PEM 块类型为 %q, 期望 %q（不支持加密私钥或其他算法私钥）", block.Type, pemTypePrivateKey)
|
||
}
|
||
|
||
key, err := x509.ParsePKCS8PrivateKey(block.Bytes)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("解析 PKCS#8 私钥失败: %w", err)
|
||
}
|
||
priv, ok := key.(ed25519.PrivateKey)
|
||
if !ok {
|
||
return nil, fmt.Errorf("PEM 中的私钥类型为 %T, 不是 Ed25519 私钥", key)
|
||
}
|
||
if len(priv) != PrivateKeySize {
|
||
return nil, fmt.Errorf("Ed25519 私钥长度非法: 期望 %d 字节, 实际 %d 字节", PrivateKeySize, len(priv))
|
||
}
|
||
return priv, nil
|
||
}
|
||
|
||
// ParsePublicKeyPEM 解析 PKIX 的 Ed25519 公钥 PEM。
|
||
//
|
||
// 只接受块类型为 "PUBLIC KEY" 的 PEM，并强制校验解析结果的具体类型与长度：
|
||
// 传入 RSA/ECDSA 公钥、证书或截断数据都会返回错误，绝不会因类型断言而 panic。
|
||
func ParsePublicKeyPEM(data []byte) (ed25519.PublicKey, error) {
|
||
block, _ := pem.Decode(data)
|
||
if block == nil {
|
||
return nil, errors.New("解析 Ed25519 公钥 PEM 失败: 数据不是合法的 PEM")
|
||
}
|
||
if block.Type != pemTypePublicKey {
|
||
return nil, fmt.Errorf("解析 Ed25519 公钥 PEM 失败: PEM 块类型为 %q, 期望 %q", block.Type, pemTypePublicKey)
|
||
}
|
||
|
||
key, err := x509.ParsePKIXPublicKey(block.Bytes)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("解析 PKIX 公钥失败: %w", err)
|
||
}
|
||
pub, ok := key.(ed25519.PublicKey)
|
||
if !ok {
|
||
return nil, fmt.Errorf("PEM 中的公钥类型为 %T, 不是 Ed25519 公钥", key)
|
||
}
|
||
if len(pub) != PublicKeySize {
|
||
return nil, fmt.Errorf("Ed25519 公钥长度非法: 期望 %d 字节, 实际 %d 字节", PublicKeySize, len(pub))
|
||
}
|
||
return pub, nil
|
||
}
|
||
|
||
// LoadPrivateKey 从文件读取并解析 PKCS#8 的 Ed25519 私钥。
|
||
//
|
||
// 文件不存在、不可读或内容非法都返回错误。请确保该路径的访问权限受控，
|
||
// 私钥内容不会出现在任何返回值或日志里。
|
||
func LoadPrivateKey(path string) (ed25519.PrivateKey, error) {
|
||
data, err := os.ReadFile(path)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("读取 Ed25519 私钥文件 %q 失败: %w", path, err)
|
||
}
|
||
return ParsePrivateKeyPEM(data)
|
||
}
|
||
|
||
// LoadPublicKey 从文件读取并解析 PKIX 的 Ed25519 公钥。
|
||
func LoadPublicKey(path string) (ed25519.PublicKey, error) {
|
||
data, err := os.ReadFile(path)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("读取 Ed25519 公钥文件 %q 失败: %w", path, err)
|
||
}
|
||
return ParsePublicKeyPEM(data)
|
||
}
|
||
|
||
// SaveKeyPair 生成一对新的 Ed25519 密钥并写入两个文件。
|
||
//
|
||
// privatePath 以 0600 权限写入（PKCS#8 PEM），publicPath 以 0644 权限写入
|
||
// （PKIX PEM）；已存在的同名文件会被覆盖。若公钥写入失败，会尽力删除刚写入的
|
||
// 私钥文件以免留下不一致的残片。注意：在 Windows 上 os.WriteFile 的权限位只
|
||
// 影响只读属性，私钥文件的访问控制需依赖目录权限另行加固。
|
||
func SaveKeyPair(privatePath, publicPath string) error {
|
||
privatePEM, publicPEM, err := GenerateKeyPEM()
|
||
if err != nil {
|
||
return err
|
||
}
|
||
|
||
if err := os.WriteFile(privatePath, privatePEM, privateFileMode); err != nil {
|
||
return fmt.Errorf("写入 Ed25519 私钥文件 %q 失败: %w", privatePath, err)
|
||
}
|
||
if err := os.WriteFile(publicPath, publicPEM, publicFileMode); err != nil {
|
||
if removeErr := os.Remove(privatePath); removeErr != nil {
|
||
return fmt.Errorf("写入 Ed25519 公钥文件 %q 失败: %w（回滚私钥文件 %q 也失败: %v）", publicPath, err, privatePath, removeErr)
|
||
}
|
||
return fmt.Errorf("写入 Ed25519 公钥文件 %q 失败: %w（已回滚私钥文件）", publicPath, err)
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// Sign 使用 Ed25519 私钥对 message 签名，返回 SignatureSize 字节的原始签名。
|
||
//
|
||
// message 可以为空或任意长度，Ed25519 内部会先做哈希，调用方无需自行预哈希。
|
||
// 私钥长度不等于 PrivateKeySize（含 nil）时返回错误，不会 panic。
|
||
// 签名是确定性的：同一私钥与同一消息总是得到相同签名，便于做可复现的比对。
|
||
func Sign(priv ed25519.PrivateKey, message []byte) ([]byte, error) {
|
||
if len(priv) != PrivateKeySize {
|
||
return nil, fmt.Errorf("Ed25519 私钥长度非法: 期望 %d 字节, 实际 %d 字节", PrivateKeySize, len(priv))
|
||
}
|
||
return ed25519.Sign(priv, message), nil
|
||
}
|
||
|
||
// Verify 校验 signature 是否为 pub 对 message 的有效 Ed25519 签名。
|
||
//
|
||
// 校验通过返回 nil，否则返回错误。签名长度不是 SignatureSize、公钥长度不是
|
||
// PublicKeySize（含 nil）时同样返回错误：标准库 ed25519.Verify 对错误长度会
|
||
// panic，本函数在调用前已完成长度校验。
|
||
//
|
||
// 安全提醒：返回的错误不区分"消息被篡改"与"签名被篡改"，以免给攻击者提供
|
||
// 额外信息；验签失败只应表现为"拒绝"，不要据此重试或降级到其他算法。
|
||
func Verify(pub ed25519.PublicKey, message, signature []byte) error {
|
||
if len(pub) != PublicKeySize {
|
||
return fmt.Errorf("Ed25519 公钥长度非法: 期望 %d 字节, 实际 %d 字节", PublicKeySize, len(pub))
|
||
}
|
||
if len(signature) != SignatureSize {
|
||
return fmt.Errorf("Ed25519 签名长度非法: 期望 %d 字节, 实际 %d 字节", SignatureSize, len(signature))
|
||
}
|
||
if !ed25519.Verify(pub, message, signature) {
|
||
return errors.New("Ed25519 验签失败: 签名与消息或公钥不匹配")
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// SignToBase64 对 message 签名并返回标准 Base64 编码的签名文本，
|
||
// 便于放进 JSON、HTTP 头或数据库字段。
|
||
//
|
||
// 私钥非法时返回错误；返回值不是密钥材料，可以安全传输。
|
||
func SignToBase64(priv ed25519.PrivateKey, message []byte) (string, error) {
|
||
signature, err := Sign(priv, message)
|
||
if err != nil {
|
||
return "", err
|
||
}
|
||
return base64.StdEncoding.EncodeToString(signature), nil
|
||
}
|
||
|
||
// VerifyFromBase64 校验标准 Base64 编码的签名。
|
||
//
|
||
// signatureB64 非法 Base64、解码后长度不为 SignatureSize，或验签不通过时
|
||
// 均返回错误；公钥非法同样返回错误，不会 panic。
|
||
func VerifyFromBase64(pub ed25519.PublicKey, message []byte, signatureB64 string) error {
|
||
signature, err := base64.StdEncoding.DecodeString(signatureB64)
|
||
if err != nil {
|
||
return fmt.Errorf("Base64 解码 Ed25519 签名失败: %w", err)
|
||
}
|
||
return Verify(pub, message, signature)
|
||
}
|