encryptx/blake2x/blake2x.go

// 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
}