120 lines
3.0 KiB
Markdown
120 lines
3.0 KiB
Markdown
|
# 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`（见下方能力矩阵）
|
|||
|
|
|
|||
|
|
## 安装
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
go get b612.me/starcrypto
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 推荐用法（安全优先）
|
|||
|
|
|
|||
|
|
优先使用带认证的 AEAD：
|
|||
|
|
|
|||
|
|
- `EncryptAesGCM/DecryptAesGCM`
|
|||
|
|
- `EncryptSM4GCM/DecryptSM4GCM`
|
|||
|
|
- `EncryptChaCha20Poly1305/DecryptChaCha20Poly1305`
|
|||
|
|
|
|||
|
|
或使用统一选项接口（默认 `GCM`）：
|
|||
|
|
|
|||
|
|
- `EncryptAesWithOptions/DecryptAesWithOptions`
|
|||
|
|
- `EncryptSM4WithOptions/DecryptSM4WithOptions`
|
|||
|
|
|
|||
|
|
> `CBC/CFB/OFB/CTR/ECB` 仅提供机密性，不提供完整性校验，可能被篡改后无法检测。
|
|||
|
|
|
|||
|
|
## 快速示例
|
|||
|
|
|
|||
|
|
### 统一 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 CBC 流式接口（兼容模式）
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
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`。
|