crypto-sm/AI.md

# AI Coding Context: @go/crypto-sm

本索引供 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 (国密非对称)
- `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)`
- `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`
- `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)`
- `func (s *SM4Cipher) Encrypt(data, key, iv []byte) ([]byte, error)`
- `func (s *SM4Cipher) Decrypt(data, key, iv []byte) ([]byte, error)`

## 🧩 典型模式 (Best Practices)

*   **✅ 安全处理 (SafeBuf 优先)**:
    ```go
    sb := safe.NewSafeBuf(sensitiveData)
    encrypted, _ := sm4.Encrypt(sb)
    decSb, _ := sm4.Decrypt(encrypted)
    defer decSb.Close()
    ```

*   **✅ 鲁棒性业务 (Must/Try 模式)**:
    ```go
    config := sm4.TryDecrypt(configData)
    sig := sm2.MustSign(data)
    ```