starcrypto

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

特性

• 根包直调 + 子包分层（asymm / symm / hashx / encodingx / paddingx 等）
• 对称算法：AES、SM4、DES、3DES、ChaCha20、ChaCha20-Poly1305
• 非对称算法：RSA、ECDSA、SM2、SM9
• 哈希与消息认证：SHA 系列、MD5/MD4、RIPEMD160、SM3、CRC32/CRC32A、HMAC
• 编解码：Base64、Base85、Base91、Base128
• 支持内存 []byte 与流式 io.Reader/io.Writer（见下方能力矩阵）

安装

go get b612.me/starcrypto

推荐用法（安全优先）

优先使用带认证的 AEAD：

• EncryptAesGCM/DecryptAesGCM
• EncryptSM4GCM/DecryptSM4GCM
• EncryptChaCha20Poly1305/DecryptChaCha20Poly1305

或使用统一选项接口（默认 GCM）：

• EncryptAesWithOptions/DecryptAesWithOptions
• EncryptSM4WithOptions/DecryptSM4WithOptions

CBC/CFB/OFB/CTR/ECB 仅提供机密性，不提供完整性校验，可能被篡改后无法检测。

快速示例

统一 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 CBC 流式接口（兼容模式）

package main

import (
	"bytes"
	"log"

	"b612.me/starcrypto"
)

func main() {
	key := []byte("0123456789abcdef")
	iv := []byte("abcdef9876543210")

	src := bytes.NewReader([]byte("stream content"))
	encBuf := &bytes.Buffer{}
	decBuf := &bytes.Buffer{}

	if err := starcrypto.EncryptAesCBCStream(encBuf, src, key, iv, ""); err != nil {
		log.Fatal(err)
	}
	if err := starcrypto.DecryptAesCBCStream(decBuf, bytes.NewReader(encBuf.Bytes()), key, iv, ""); err != nil {
		log.Fatal(err)
	}
}

算法能力矩阵

算法	模式 / 方案	AEAD	Stream	建议
AES	ECB/CBC/CFB/OFB/CTR/GCM	GCM: 是	是	生产优先 GCM
SM4	ECB/CBC/CFB/OFB/CTR/GCM	GCM: 是	是	生产优先 GCM
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/ChaCha20 不使用填充

兼容性说明

库中保留了部分历史/兼容用途算法与接口（例如 ECB、DES/3DES）。如无兼容要求，建议使用 AEAD 方案并统一通过 CipherOptions 管理参数。

许可证

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