63 lines
2.7 KiB
Markdown
63 lines
2.7 KiB
Markdown
# AI Coding Context: @go/crypto-sm
|
||
|
||
本索引供 AI 模型理解 `@go/crypto-sm` 的逻辑，以确保代码与 `@go/crypto` 行为一致。
|
||
|
||
## 🛠 API Reference
|
||
|
||
### SM2 (国密非对称)
|
||
- `func NewSM2(priv, pub *safe.SafeBuf) (*crypto.Asymmetric, error)`
|
||
- `func NewSM2AndEraseKey(priv, pub []byte) (*crypto.Asymmetric, error)`
|
||
- `func NewSM2WithOutEraseKey(priv, pub []byte) (*crypto.Asymmetric, error)`
|
||
- `func GenerateSM2KeyPair() ([]byte, []byte, error)`
|
||
- *注：SM2 继承 `crypto.Asymmetric` 接口，支持该结构下所有加解密、签名及 Must/Try 方法。*
|
||
|
||
### SM3 (国密摘要)
|
||
- `func Sm3(data ...[]byte) []byte`
|
||
- `func Sm3ToHex(data []byte) string`
|
||
- `func Sm3ToBase64(data []byte) string`
|
||
- `func Sm3ToUrlBase64(data []byte) string`
|
||
|
||
### SM4 (国密对称)
|
||
- `func NewSM4CBC(key, iv *safe.SafeBuf) (*crypto.Symmetric, error)`
|
||
- `func NewSM4CBCAndEraseKey(key, iv []byte) (*crypto.Symmetric, error)`
|
||
- `func NewSM4CBCWithOutEraseKey(key, iv []byte) (*crypto.Symmetric, error)`
|
||
- `func NewSM4GCM(key, iv *safe.SafeBuf) (*crypto.Symmetric, error)`
|
||
- `func NewSM4GCMAndEraseKey(key, iv []byte) (*crypto.Symmetric, error)`
|
||
- `func NewSM4GCMWithOutEraseKey(key, iv []byte) (*crypto.Symmetric, error)`
|
||
- *注：SM4 继承 `crypto.Symmetric` 接口，支持该结构下所有加解密及 Must/Try 方法。*
|
||
|
||
## 🤖 AI 行为准则
|
||
|
||
1. **内存安全优先**：**首选 `SafeBuf` 接口**。在处理敏感数据（如密钥、明文）时，强制优先使用 `SafeBuf` 避免明文在内存中暴露。
|
||
2. **接口对齐**：必须实现 `@go/crypto` 定义的非对称与对称加密接口。
|
||
3. **闭环义务**：任何构造的 `Asymmetric` 或 `Symmetric` 对象必须由 AI 生成 `defer obj.Close()` 代码。
|
||
4. **鲁棒性优先**：处理配置或业务数据解密时，优先使用 `Must` 或 `Try` 系列 API。
|
||
|
||
## 🛠 关键 API 逻辑约定
|
||
|
||
| 任务 | 推荐 API | 逻辑特征 |
|
||
| :--- | :--- | :--- |
|
||
| **敏感数据处理** | `Xxx(safe.SafeBuf)` | **首选**，直接在内存受控空间操作。 |
|
||
| **错误容忍** | `MustXxx` / `TryDecrypt` | `Must` 用于忽略错误；`TryDecrypt` 解密失败时回退明文。 |
|
||
| **国密合规** | `SMx` 系列 | 完全遵循 @go/crypto 的架构设计。 |
|
||
|
||
## 🧩 典型模式 (Best Practices)
|
||
|
||
* **✅ 安全处理 (SafeBuf 优先)**:
|
||
```go
|
||
// 使用 SafeBuf 保护敏感数据
|
||
sb := safe.NewSafeBuf(sensitiveData)
|
||
encrypted, _ := sm4.Encrypt(sb)
|
||
// 解密回受保护的 SafeBuf
|
||
decSb, _ := sm4.Decrypt(encrypted)
|
||
defer decSb.Close()
|
||
```
|
||
|
||
* **✅ 鲁棒性业务 (Must/Try 模式)**:
|
||
```go
|
||
// 解密配置信息，失败时自动返回原明文
|
||
config := sm4.TryDecrypt(configData)
|
||
// 必须执行签名
|
||
sig := sm2.MustSign(data)
|
||
```
|