完善不同加密方法的使用

2026-09-30 15:49:12 +08:00
parent 034315ddbd
commit 7db722f8b9
69 changed files with 21362 additions and 2563 deletions
@@ -0,0 +1,227 @@
+// Package blake2x 提供 BLAKE2b 与 BLAKE2s 摘要计算，以及十六进制/Base64 编码与流式、文件接口。
+//
+// BLAKE2 是现代高速哈希（RFC 7693），在同等安全强度下通常比 SHA-2 更快，
+// 常用于校验和、内容寻址（如 IPFS CID）与文件指纹。
+//
+// 命名约定：
+//   - 带 B 后缀的函数（Sum256B、New256B、Hex256B 等）使用 BLAKE2b，摘要长度 1..64 字节；
+//   - 带 S 后缀的函数（Sum256S、New256S、Hex256S 等）使用 BLAKE2s，摘要长度固定 256 位；
+//   - Sum512、Sum384 是 BLAKE2b 的固定长度便捷函数；
+//   - 不带后缀的 Sum、Hex、Base64、New、SumReader、HexReader、HexFile 等价于 BLAKE2b-512（默认变体）。
+//
+// 注意 BLAKE2b-256 与 BLAKE2s-256 摘要长度相同但结果完全不同，不可互换。
+//
+// 本包只暴露无密钥（unkeyed）哈希。带密钥的 BLAKE2 等同于 MAC，应按 MAC 的规范使用，
+// 请使用专门的 MAC 包（如 hmacx）或直接调用 golang.org/x/crypto/blake2b.New(size, key)。
+package blake2x
+
+import (
+	"encoding/base64"
+	"encoding/hex"
+	"fmt"
+	"hash"
+	"io"
+	"os"
+
+	"golang.org/x/crypto/blake2b"
+	"golang.org/x/crypto/blake2s"
+)
+
+const (
+	// BlockSizeB 是 BLAKE2b 分组的字节数（128）。
+	BlockSizeB = blake2b.BlockSize
+	// BlockSizeS 是 BLAKE2s 分组的字节数（64）。
+	BlockSizeS = blake2s.BlockSize
+	// SizeB512 是 BLAKE2b-512 摘要的字节数（64）。
+	SizeB512 = blake2b.Size
+	// SizeB384 是 BLAKE2b-384 摘要的字节数（48）。
+	SizeB384 = blake2b.Size384
+	// SizeB256 是 BLAKE2b-256 摘要的字节数（32）。
+	SizeB256 = blake2b.Size256
+	// SizeS256 是 BLAKE2s-256 摘要的字节数（32）。
+	SizeS256 = blake2s.Size
+	// MinSizeB 是 BLAKE2b 允许的最小摘要字节数。
+	MinSizeB = 1
+	// MaxSizeB 是 BLAKE2b 允许的最大摘要字节数（64）。
+	MaxSizeB = blake2b.Size
+)
+
+// NewB 按指定摘要长度创建 BLAKE2b 哈希；size 必须在 [MinSizeB, MaxSizeB] 内，否则返回 error。
+func NewB(size int) (hash.Hash, error) {
+	if size < MinSizeB || size > MaxSizeB {
+		return nil, fmt.Errorf("blake2x: BLAKE2b 摘要长度 %d 超出范围 [%d, %d]", size, MinSizeB, MaxSizeB)
+	}
+	h, err := blake2b.New(size, nil)
+	if err != nil {
+		return nil, fmt.Errorf("blake2x: 创建 BLAKE2b-%d 失败: %w", size, err)
+	}
+	return h, nil
+}
+
+// New512 返回 BLAKE2b-512 哈希。
+func New512() (hash.Hash, error) {
+	return NewB(SizeB512)
+}
+
+// New384 返回 BLAKE2b-384 哈希。
+func New384() (hash.Hash, error) {
+	return NewB(SizeB384)
+}
+
+// New256B 返回 BLAKE2b-256 哈希。
+func New256B() (hash.Hash, error) {
+	return NewB(SizeB256)
+}
+
+// New256S 返回 BLAKE2s-256 哈希。
+func New256S() (hash.Hash, error) {
+	h, err := blake2s.New256(nil)
+	if err != nil {
+		return nil, fmt.Errorf("blake2x: 创建 BLAKE2s-256 失败: %w", err)
+	}
+	return h, nil
+}
+
+// New 等价于 New512。
+func New() (hash.Hash, error) {
+	return New512()
+}
+
+// SumB 返回 data 的 BLAKE2b 摘要，长度由 size 指定；
+// size 必须在 [MinSizeB, MaxSizeB] 内，否则返回 error。
+func SumB(size int, data []byte) ([]byte, error) {
+	h, err := NewB(size)
+	if err != nil {
+		return nil, err
+	}
+	_, _ = h.Write(data)
+	return h.Sum(nil), nil
+}
+
+// Sum512 返回 data 的 BLAKE2b-512 摘要（SizeB512 字节原始数据）。
+func Sum512(data []byte) []byte {
+	s := blake2b.Sum512(data)
+	return s[:]
+}
+
+// Sum384 返回 data 的 BLAKE2b-384 摘要（SizeB384 字节原始数据）。
+func Sum384(data []byte) []byte {
+	s := blake2b.Sum384(data)
+	return s[:]
+}
+
+// Sum256B 返回 data 的 BLAKE2b-256 摘要（SizeB256 字节原始数据）。
+func Sum256B(data []byte) []byte {
+	s := blake2b.Sum256(data)
+	return s[:]
+}
+
+// Sum256S 返回 data 的 BLAKE2s-256 摘要（SizeS256 字节原始数据）。
+func Sum256S(data []byte) []byte {
+	s := blake2s.Sum256(data)
+	return s[:]
+}
+
+// Sum 等价于 Sum512。
+func Sum(data []byte) []byte {
+	return Sum512(data)
+}
+
+// HexB 返回 data 的 BLAKE2b 摘要的小写十六进制字符串，长度由 size 指定。
+func HexB(size int, data []byte) (string, error) {
+	sum, err := SumB(size, data)
+	if err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(sum), nil
+}
+
+// Hex512 返回 data 的 BLAKE2b-512 摘要的小写十六进制字符串。
+func Hex512(data []byte) string {
+	return hex.EncodeToString(Sum512(data))
+}
+
+// Hex384 返回 data 的 BLAKE2b-384 摘要的小写十六进制字符串。
+func Hex384(data []byte) string {
+	return hex.EncodeToString(Sum384(data))
+}
+
+// Hex256B 返回 data 的 BLAKE2b-256 摘要的小写十六进制字符串。
+func Hex256B(data []byte) string {
+	return hex.EncodeToString(Sum256B(data))
+}
+
+// Hex256S 返回 data 的 BLAKE2s-256 摘要的小写十六进制字符串。
+func Hex256S(data []byte) string {
+	return hex.EncodeToString(Sum256S(data))
+}
+
+// Hex 等价于 Hex512。
+func Hex(data []byte) string {
+	return Hex512(data)
+}
+
+// Base64Sum512 返回 data 的 BLAKE2b-512 摘要的标准 Base64 字符串。
+func Base64Sum512(data []byte) string {
+	return base64.StdEncoding.EncodeToString(Sum512(data))
+}
+
+// Base64Sum384 返回 data 的 BLAKE2b-384 摘要的标准 Base64 字符串。
+func Base64Sum384(data []byte) string {
+	return base64.StdEncoding.EncodeToString(Sum384(data))
+}
+
+// Base64Sum256B 返回 data 的 BLAKE2b-256 摘要的标准 Base64 字符串。
+func Base64Sum256B(data []byte) string {
+	return base64.StdEncoding.EncodeToString(Sum256B(data))
+}
+
+// Base64Sum256S 返回 data 的 BLAKE2s-256 摘要的标准 Base64 字符串。
+func Base64Sum256S(data []byte) string {
+	return base64.StdEncoding.EncodeToString(Sum256S(data))
+}
+
+// Base64 等价于 Base64Sum512。
+func Base64(data []byte) string {
+	return Base64Sum512(data)
+}
+
+// SumReader 读取 r 中的全部数据并返回其 BLAKE2b-512 摘要。
+func SumReader(r io.Reader) ([]byte, error) {
+	if r == nil {
+		return nil, fmt.Errorf("blake2x: 读取器为 nil")
+	}
+	h, err := New512()
+	if err != nil {
+		return nil, err
+	}
+	if _, err := io.Copy(h, r); err != nil {
+		return nil, fmt.Errorf("blake2x: 读取数据失败: %w", err)
+	}
+	return h.Sum(nil), nil
+}
+
+// HexReader 读取 r 中的全部数据并返回其 BLAKE2b-512 摘要的小写十六进制字符串。
+func HexReader(r io.Reader) (string, error) {
+	sum, err := SumReader(r)
+	if err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(sum), nil
+}
+
+// HexFile 计算 path 所指向文件的 BLAKE2b-512 摘要并返回小写十六进制字符串；
+// 文件不存在或读取失败时返回包装后的 error，不 panic。
+func HexFile(path string) (string, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return "", fmt.Errorf("blake2x: 打开文件 %q 失败: %w", path, err)
+	}
+	defer f.Close()
+
+	sum, err := SumReader(f)
+	if err != nil {
+		return "", fmt.Errorf("blake2x: 计算文件 %q 摘要失败: %w", path, err)
+	}
+	return hex.EncodeToString(sum), nil
+}