starcrypto/README.md

starcrypto

starcrypto 是一个 Go 单包聚合风格的密码学工具库：根包可直接调用，同时内部拆分为子包实现，兼顾易用性与可维护性。

安装

go get b612.me/starcrypto

特性

• 根包直调 + 子包分层（asymm / symm / hashx / encodingx / paddingx 等）
• 对称算法：AES、SM4、DES、3DES、ChaCha20、ChaCha20-Poly1305
• AEAD：AES-GCM/AES-CCM、SM4-GCM/SM4-CCM、ChaCha20-Poly1305
• 存储加密：AES-XTS、SM4-XTS（双 key，支持 data unit 索引与流式）
• 非对称算法：RSA、ECDSA、SM2、SM9
• 哈希与消息认证：SHA 系列、MD5/MD4、RIPEMD160、SM3、CRC32/CRC32A、HMAC
• 支持内存 []byte 与流式 io.Reader/io.Writer

推荐用法（安全优先）

• 通用数据传输优先使用 AEAD：
  • EncryptAesGCM/DecryptAesGCM
  • EncryptAesCCM/DecryptAesCCM
  • EncryptSM4GCM/DecryptSM4GCM
  • EncryptSM4CCM/DecryptSM4CCM
  • EncryptChaCha20Poly1305/DecryptChaCha20Poly1305
• 磁盘/扇区类场景可用 XTS：
  • EncryptAesXTS/DecryptAesXTS
  • EncryptSM4XTS/DecryptSM4XTS
• 统一选项接口（默认 GCM）：
  • EncryptAesWithOptions/DecryptAesWithOptions
  • EncryptSM4WithOptions/DecryptSM4WithOptions

CBC/CFB/OFB/CTR/ECB/XTS 不提供完整性校验，不能替代 AEAD 的篡改检测能力。 AEAD (GCM/CCM/ChaCha20-Poly1305) 下，同一把 key 绝不能重复使用同一个 nonce。 使用 CipherOptions 时，AEAD 模式仅读取 Nonce 字段，不再回退 IV。 GCM/CCM 流解密在 legacy 兼容分支会缓冲完整密文到内存；大文件建议使用分块流格式（带 SCG1/SCC1 头）。

XTS 约束（重要）

• 两个密钥分开传入：key1, key2，且长度必须相同且非空。
• dataUnitSize（数据单元大小）由调用方自定义，但必须是正整数且为 16 的倍数。
• dataUnitIndex 必须与存储层的逻辑块映射保持稳定一致；同一数据单元在加密和解密时索引必须一致。
• 当前实现不做 CTS（ciphertext stealing）。
• 非流式 API：输入长度必须满足 len(data) % 16 == 0，否则直接返回错误。
• 流式 API：最终尾块若不是 16 字节对齐会返回错误。

文件随机填充

• FillWithRandom 使用 math/rand 伪随机，速度更高，但不适合安全用途。
• FillWithCryptoRandom 使用 crypto/rand，安全性更高，但速度可能受限。

快速示例

统一 Options（默认 GCM）

package main

import (
	"fmt"
	"log"

	"b612.me/starcrypto"
)

func main() {
	key := []byte("0123456789abcdef")
	nonce := []byte("123456789012")
	plain := []byte("hello starcrypto")

	opts := &starcrypto.CipherOptions{Nonce: nonce}
	enc, err := starcrypto.EncryptAesWithOptions(plain, key, opts)
	if err != nil {
		log.Fatal(err)
	}
	dec, err := starcrypto.DecryptAesWithOptions(enc, key, opts)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(dec))
}

AES-XTS（按 data unit）

package main

import (
	"bytes"
	"log"

	"b612.me/starcrypto"
)

func main() {
	k1 := []byte("0123456789abcdef")
	k2 := []byte("fedcba9876543210")
	plain := bytes.Repeat([]byte("0123456789abcdef"), 8) // 128 bytes, 16-byte aligned

	// 每个 data unit 64 字节
	enc, err := starcrypto.EncryptAesXTS(plain, k1, k2, 64)
	if err != nil {
		log.Fatal(err)
	}
	dec, err := starcrypto.DecryptAesXTS(enc, k1, k2, 64)
	if err != nil {
		log.Fatal(err)
	}
	_ = dec
}

算法能力矩阵

算法	模式 / 方案	AEAD	Stream	建议
AES	ECB/CBC/CFB/OFB/CTR/GCM/CCM/XTS	GCM/CCM: 是；XTS: 否	是	生产优先 GCM/CCM；存储场景可用 XTS
SM4	ECB/CBC/CFB/OFB/CTR/GCM/CCM/XTS	GCM/CCM: 是；XTS: 否	是	生产优先 GCM/CCM；存储场景可用 XTS
ChaCha20	ChaCha20 / ChaCha20-Poly1305	Poly1305: 是	ChaCha20: 是	生产优先 ChaCha20-Poly1305
DES	CBC	否	是	仅兼容历史系统
3DES	CBC	否	是	仅兼容历史系统

默认填充策略

• AES/SM4 的 CBC/ECB 默认：PKCS7
• DES/3DES 的 CBC 默认：PKCS5
• CFB/OFB/CTR/GCM/CCM/XTS/ChaCha20 不使用填充

兼容性说明

库中保留了部分历史/兼容用途算法与接口（例如 ECB、DES/3DES）。如无兼容要求，建议优先使用 AEAD 方案。

• hashx 的 SumAll / FileSumAll / FileSum 对未知算法名会返回错误（不再静默忽略）。

许可证

本项目使用 Apache-2.0 许可证，详见 LICENSE。