From 8887fe52f3d3ce40ea648c17dcf286d5643a7964 Mon Sep 17 00:00:00 2001 From: AI Engineer Date: Fri, 24 Apr 2026 16:58:25 +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 | 80 ++++++++++++++++++++++++++++------------------------------ go.mod | 6 ++--- 2 files changed, 42 insertions(+), 44 deletions(-) diff --git a/AI.md b/AI.md index cfe9891..aa96ead 100644 --- a/AI.md +++ b/AI.md @@ -2,11 +2,25 @@ 本索引供 AI 模型理解 `@go/crypto` 的逻辑，以生成符合本项目“安全闭环、性能分级、语义一致”哲学的代码。 +## 🤖 AI 行为准则 +1. **内存安全优先**：首选 `SafeBuf` 接口处理敏感数据（密钥、明文）。 +2. **场景化构造选择**：C端推荐 `AndEraseKey` 系列；S端高频场景使用 `New...WithOutEraseKey(..., true)` 进入 **FastMode**。 +3. **闭环义务**：任何构造的 `Asymmetric` 或 `Symmetric` 对象，生成的代码必须包含 `defer obj.Close()`。 +4. **接口一致性**：所有非对称算法必须实现 `ParsePrivateKey` 与 `ParsePublicKey`。 + ## 🛠 API Reference -### 对称加密 (AES-CBC/GCM) +### 对称加密 (Symmetric) +- `func NewSymmetric(cipher SymmetricCipher, safeKeyBuf, safeIvBuf *safe.SafeBuf) (*Symmetric, error)` +- `func NewSymmetricAndEraseKey(cipher SymmetricCipher, key, iv []byte) (*Symmetric, error)` +- `func NewSymmetricWithOutEraseKey(cipher SymmetricCipher, key, iv []byte) (*Symmetric, error)` +- `func NewAESCBC(safeKeyBuf, safeIvBuf *safe.SafeBuf) (*Symmetric, error)` - `func NewAESCBCAndEraseKey(key, iv []byte) (*Symmetric, error)` +- `func NewAESCBCWithOutEraseKey(key, iv []byte) (*Symmetric, error)` +- `func NewAESGCM(safeKeyBuf, safeIvBuf *safe.SafeBuf) (*Symmetric, error)` - `func NewAESGCMAndEraseKey(key, iv []byte) (*Symmetric, error)` +- `func NewAESGCMWithOutEraseKey(key, iv []byte) (*Symmetric, error)` +- `func (s *Symmetric) Close()` - `func (s *Symmetric) Encrypt(safeBuf *safe.SafeBuf) ([]byte, error)` - `func (s *Symmetric) EncryptAndErase(data []byte) ([]byte, error)` - `func (s *Symmetric) EncryptBytes(data []byte) ([]byte, error)` @@ -16,58 +30,42 @@ - `func (s *Symmetric) MustDecrypt(data []byte) []byte` - `func (s *Symmetric) TryDecrypt(data []byte) []byte` -### 非对称加密 (RSA/ECDSA/Ed25519/X25519) -- `func NewRSAndEraseKey(priv, pub []byte) (*Asymmetric, error)` -- `func NewECDSAndEraseKey(priv, pub []byte) (*Asymmetric, error)` -- `func NewED25519AndEraseKey(priv, pub []byte) (*Asymmetric, error)` -- `func NewX25519AndEraseKey(priv, pub []byte) (*Asymmetric, error)` -- `func NewAsymmetricWithoutEraseKey(algo, priv, pub, fastMode) (*Asymmetric, error)` +### 非对称加密 (Asymmetric) +- `func NewAsymmetric(algorithm AsymmetricAlgorithm, safePrivateKeyBuf, safePublicKeyBuf *safe.SafeBuf) (*Asymmetric, error)` +- `func NewAsymmetricAndEraseKey(algorithm AsymmetricAlgorithm, privateKey, publicKey []byte) (*Asymmetric, error)` +- `func NewAsymmetricWithoutEraseKey(algorithm AsymmetricAlgorithm, privateKey, publicKey []byte, fastMode bool) (*Asymmetric, error)` +- `func NewRSA(priv, pub *safe.SafeBuf) (*Asymmetric, error)` / `NewRSAndEraseKey(...)` / `NewRSAWithOutEraseKey(...)` +- `func NewECDSA(priv, pub *safe.SafeBuf) (*Asymmetric, error)` / `NewECDSAndEraseKey(...)` / `NewECDSAWithOutEraseKey(...)` +- `func NewED25519(priv, pub *safe.SafeBuf) (*Asymmetric, error)` / `NewED25519AndEraseKey(...)` / `NewED25519WithOutEraseKey(...)` +- `func NewX25519(priv, pub *safe.SafeBuf) (*Asymmetric, error)` / `NewX25519AndEraseKey(...)` / `NewX25519WithOutEraseKey(...)` +- `func (a *Asymmetric) Close()` - `func (a *Asymmetric) Sign(data []byte, hash ...crypto.Hash) ([]byte, error)` - `func (a *Asymmetric) SignAndErase(data []byte, hash ...crypto.Hash) ([]byte, error)` - `func (a *Asymmetric) MustSign(data []byte, hash ...crypto.Hash) []byte` -- `func (a *Asymmetric) Verify(data, signature []byte, hash ...crypto.Hash) (bool, error)` -- `func (a *Asymmetric) MustVerify(data, signature []byte, hash ...crypto.Hash) bool` +- `func (a *Asymmetric) Verify(data []byte, signature []byte, hash ...crypto.Hash) (bool, error)` +- `func (a *Asymmetric) MustVerify(data []byte, signature []byte, hash ...crypto.Hash) bool` - `func (a *Asymmetric) Encrypt(safeBuf *safe.SafeBuf) ([]byte, error)` - `func (a *Asymmetric) EncryptAndErase(data []byte) ([]byte, error)` +- `func (a *Asymmetric) EncryptBytes(data []byte) ([]byte, error)` - `func (a *Asymmetric) MustEncrypt(data []byte) []byte` - `func (a *Asymmetric) Decrypt(data []byte) (*safe.SafeBuf, error)` - `func (a *Asymmetric) DecryptBytes(data []byte) ([]byte, error)` - `func (a *Asymmetric) MustDecrypt(data []byte) []byte` - `func (a *Asymmetric) TryDecrypt(data []byte) []byte` -### Hash 系列 (MD5/SHA) -- `func MD5(data ...[]byte) []byte` / `func MD5ToHex(d []byte) string` -- `func Sha256ToHex(d []byte) string` / `func Sha256ToBase64(d []byte) string` / `func Sha256ToUrlBase64(d []byte) string` -- *其他算法 (Sha1, Sha512) 均支持上述 Hex/Base64/UrlBase64 变体* - ### 密钥对生成 - `func GenerateRSAKeyPair(bitSize int) (priv, pub []byte, err error)` - `func GenerateECDSAKeyPair(bitSize int) (priv, pub []byte, err error)` - `func GenerateEd25519KeyPair() (priv, pub []byte, err error)` - `func GenerateX25519KeyPair() (priv, pub []byte, err error)` -## 🤖 AI 行为准则 - -1. **内存安全优先**：**首选 `SafeBuf` 接口**（如 `Encrypt(safeBuf)` 或 `Decrypt(data)` 返回 `SafeBuf`）。 - * 在处理敏感数据（如密钥、明文）时，强制优先使用 `SafeBuf` 避免明文在内存中暴露。 -2. **场景化构造选择**： - * **C端/低频场景**：强制推荐 `AndEraseKey` 系列（如 `NewAESGCMAndEraseKey`），安全至上。 - * **S端/高频场景**：推荐使用 `NewAsymmetricWithoutEraseKey(..., true)` 进入 **FastMode**。 -3. **API 优先级**： - * 摘要计算：优先使用 `XxxToHex` 或 `XxxToBase64` 快捷函数。 - * 签名验证：默认采用 SHA256。 -4. **闭环义务**：任何构造的 `Asymmetric` 或 `Symmetric` 对象必须由 AI 生成 `defer obj.Close()` 代码。 -5. **数据展现**：严禁在 `go/crypto` 中寻找二进制展现逻辑，必须调用 `go/encoding` 处理。 - -## 🛠 关键 API 逻辑约定 - -| 任务 | 推荐 API | 逻辑特征 | -| :--- | :--- | :--- | -| **敏感数据处理** | `Xxx(safe.SafeBuf)` | **首选**，直接在内存受控空间操作。 | -| **混合加解密** | `Asymmetric.Encrypt` | 针对 ECDSA/X25519 自动执行混合加密。 | -| **错误容忍** | `MustXxx` / `TryDecrypt` | `Must` 用于忽略错误；`TryDecrypt` 解密失败时回退明文。 | -| **高并发签名** | `FastMode` | 启用缓存，QPS 吞吐量数倍提升。 | -| **混淆防御** | `NewSymmetric...` | 允许传入超长 Key，内部自动截断以隐藏密钥特征。 | +### Hash 与填充辅助 +- `func MD5(data ...[]byte) []byte` / `MD5ToHex(data) string` / `MD5ToBase64(data) string` / `MD5ToUrlBase64(data) string` +- `func Sha256(data ...[]byte) []byte` / `Sha256ToHex(data) string` / `Sha256ToBase64(data) string` / `Sha256ToUrlBase64(data) string` +- `func Sha512(data ...[]byte) []byte` / `Sha512ToHex(data) string` / `Sha512ToBase64(data) string` / `Sha512ToUrlBase64(data) string` +- `func HmacSha256(key []byte, data ...[]byte) []byte` +- `func Pkcs5Padding(data []byte, blockSize int) []byte` / `Pkcs5UnPadding(data []byte) []byte` +- `func AnsiX923Padding(data []byte, blockSize int) []byte` / `AnsiX923UnPadding(data []byte) []byte` ## 🧩 典型模式 (Best Practices) @@ -81,11 +79,11 @@ defer decSb.Close() ``` -* **✅ 鲁棒性业务 (Must/Try 模式)**: +* **✅ 高并发签名 (FastMode)**: ```go - // 允许配置信息解密失败时使用原样数据 - finalData := s.TryDecrypt(configData) - // 强制加密场景 - signature := a.MustSign(data) + // S端场景使用 FastMode + a, _ := crypto.NewAsymmetricWithoutEraseKey(algo, priv, pub, true) + defer a.Close() + sig := a.MustSign(data) ``` diff --git a/go.mod b/go.mod index 13d947a..df06c92 100644 --- a/go.mod +++ b/go.mod @@ -3,12 +3,12 @@ module apigo.cc/go/crypto go 1.25.0 require ( - apigo.cc/go/encoding v1.0.0 - apigo.cc/go/safe v1.0.0 + apigo.cc/go/encoding v1.0.3 + apigo.cc/go/safe v1.0.3 golang.org/x/crypto v0.50.0 ) require ( - apigo.cc/go/rand v1.0.2 // indirect + apigo.cc/go/rand v1.0.3 // indirect golang.org/x/sys v0.43.0 // indirect )