141 lines
4.4 KiB
Markdown
141 lines
4.4 KiB
Markdown
# starcrypto
|
||
|
||
`starcrypto` 是一个 Go 单包聚合风格的密码学工具库：根包可直接调用，同时内部拆分为子包实现，兼顾易用性与可维护性。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
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）
|
||
|
||
```go
|
||
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）
|
||
|
||
```go
|
||
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`。
|