crypto-sm/AI.md

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 优先):

  // 使用 SafeBuf 保护敏感数据
  sb := safe.NewSafeBuf(sensitiveData)
  encrypted, _ := sm4.Encrypt(sb)
  // 解密回受保护的 SafeBuf
  decSb, _ := sm4.Decrypt(encrypted)
  defer decSb.Close()
  

• ✅ 鲁棒性业务 (Must/Try 模式):

  // 解密配置信息，失败时自动返回原明文
  config := sm4.TryDecrypt(configData)
  // 必须执行签名
  sig := sm2.MustSign(data)