From c7f13b5de6f3d069278041041dee1f6b4bdf741d Mon Sep 17 00:00:00 2001 From: AI Engineer Date: Fri, 24 Apr 2026 16:58:27 +0800 Subject: [PATCH] =?UTF-8?q?AI:=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=B4=A2=E5=BC=95=E8=87=B3=20v1.0.3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AI.md | 36 +++++++++++++++--------------------- go.mod | 8 ++++---- 2 files changed, 19 insertions(+), 25 deletions(-) diff --git a/AI.md b/AI.md index da78a9d..bae6133 100644 --- a/AI.md +++ b/AI.md @@ -2,6 +2,13 @@ 本索引供 AI 模型理解 `@go/crypto-sm` 的逻辑，以确保代码与 `@go/crypto` 行为一致。 +## 🤖 AI 行为准则 + +1. **内存安全优先**：**首选 `SafeBuf` 接口**。在处理敏感数据（如密钥、明文）时，强制优先使用 `SafeBuf` 避免明文在内存中暴露。 +2. **接口对齐**：必须实现 `@go/crypto` 定义的非对称与对称加密接口。 +3. **闭环义务**：任何构造的 `Asymmetric` 或 `Symmetric` 对象必须由 AI 生成 `defer obj.Close()` 代码。 +4. **鲁棒性优先**：处理配置或业务数据解密时，优先使用 `Must` 或 `Try` 系列 API。 + ## 🛠 API Reference ### SM2 (国密非对称) @@ -9,7 +16,12 @@ - `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 方法。* +- `func (a *SM2Algorithm) ParsePrivateKey(der []byte) (any, error)` +- `func (a *SM2Algorithm) ParsePublicKey(der []byte) (any, error)` +- `func (a *SM2Algorithm) Sign(priv any, data []byte, hash ...stdcrypto.Hash) ([]byte, error)` +- `func (a *SM2Algorithm) Verify(pub any, data, sig []byte, hash ...stdcrypto.Hash) (bool, error)` +- `func (a *SM2Algorithm) Encrypt(pub any, data []byte) ([]byte, error)` +- `func (a *SM2Algorithm) Decrypt(priv any, data []byte) ([]byte, error)` ### SM3 (国密摘要) - `func Sm3(data ...[]byte) []byte` @@ -24,39 +36,21 @@ - `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 的架构设计。 | +- `func (s *SM4Cipher) Encrypt(data, key, iv []byte) ([]byte, error)` +- `func (s *SM4Cipher) Decrypt(data, key, iv []byte) ([]byte, error)` ## 🧩 典型模式 (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) ``` diff --git a/go.mod b/go.mod index 5e302f3..dd5be87 100644 --- a/go.mod +++ b/go.mod @@ -3,14 +3,14 @@ module apigo.cc/go/crypto-sm go 1.25.0 require ( - apigo.cc/go/crypto v1.0.0 - apigo.cc/go/encoding v1.0.0 - apigo.cc/go/safe v1.0.0 + apigo.cc/go/crypto v1.0.3 + apigo.cc/go/encoding v1.0.3 + apigo.cc/go/safe v1.0.3 github.com/emmansun/gmsm v0.28.0 ) require ( - apigo.cc/go/rand v1.0.2 // indirect + apigo.cc/go/rand v1.0.3 // indirect golang.org/x/crypto v0.50.0 // indirect golang.org/x/sys v0.43.0 // indirect )