feat(crypto): add Must/Try error handling and enhance SafeBuf documentation
This commit is contained in:
AI Engineer
parent
7b157dab0c
commit
f4005e704e
80
AI.md
80
AI.md
@ -2,38 +2,90 @@
|
||||
|
||||
本索引供 AI 模型理解 `@go/crypto` 的逻辑，以生成符合本项目“安全闭环、性能分级、语义一致”哲学的代码。
|
||||
|
||||
## 🛠 API Reference
|
||||
|
||||
### 对称加密 (AES-CBC/GCM)
|
||||
- `func NewAESCBCAndEraseKey(key, iv []byte) (*Symmetric, error)`
|
||||
- `func NewAESGCMAndEraseKey(key, iv []byte) (*Symmetric, error)`
|
||||
- `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)`
|
||||
- `func (s *Symmetric) MustEncrypt(data []byte) []byte`
|
||||
- `func (s *Symmetric) Decrypt(data []byte) (*safe.SafeBuf, error)`
|
||||
- `func (s *Symmetric) DecryptBytes(data []byte) ([]byte, error)`
|
||||
- `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)`
|
||||
- `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) Encrypt(safeBuf *safe.SafeBuf) ([]byte, error)`
|
||||
- `func (a *Asymmetric) EncryptAndErase(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. **场景化构造选择**：
|
||||
1. **内存安全优先**：**首选 `SafeBuf` 接口**（如 `Encrypt(safeBuf)` 或 `Decrypt(data)` 返回 `SafeBuf`）。
|
||||
* 在处理敏感数据（如密钥、明文）时，强制优先使用 `SafeBuf` 避免明文在内存中暴露。
|
||||
2. **场景化构造选择**：
|
||||
* **C端/低频场景**：强制推荐 `AndEraseKey` 系列（如 `NewAESGCMAndEraseKey`），安全至上。
|
||||
* **S端/高频场景**：推荐使用 `NewAsymmetricWithoutEraseKey(..., true)` 进入 **FastMode**。
|
||||
2. **API 优先级**：
|
||||
* 摘要计算：优先使用 `XxxToHex` 或 `XxxToBase64` 快捷函数，减少链式调用。
|
||||
3. **API 优先级**：
|
||||
* 摘要计算：优先使用 `XxxToHex` 或 `XxxToBase64` 快捷函数。
|
||||
* 签名验证：默认采用 SHA256。
|
||||
3. **闭环义务**：任何构造的 `Asymmetric` 或 `Symmetric` 对象必须由 AI 生成 `defer obj.Close()` 代码。
|
||||
4. **数据展现**：严禁在 `go/crypto` 中寻找二进制展现逻辑，必须调用 `go/encoding` 处理。
|
||||
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，内部自动截断以隐藏密钥特征。 |
|
||||
|
||||
## 🧩 典型模式 (Best Practices)
|
||||
|
||||
* **✅ 高性能服务端 (FastMode)**:
|
||||
* **✅ 安全传输 (SafeBuf 优先)**:
|
||||
```go
|
||||
// 适合每秒数万次的验签场景
|
||||
a, _ := crypto.NewAsymmetricWithoutEraseKey(crypto.ED25519, priv, pub, true)
|
||||
defer a.Close()
|
||||
// 对敏感数据进行加密
|
||||
sb := safe.NewSafeBuf(sensitiveData)
|
||||
encrypted, _ := s.Encrypt(sb)
|
||||
// 解密回受保护的 SafeBuf
|
||||
decSb, _ := s.Decrypt(encrypted)
|
||||
defer decSb.Close()
|
||||
```
|
||||
|
||||
* **✅ 混合加解密 (混合流)**:
|
||||
* **✅ 鲁棒性业务 (Must/Try 模式)**:
|
||||
```go
|
||||
// 对大数据进行非对称加密的唯一正确方式
|
||||
a, _ := crypto.NewX25519AndEraseKey(priv, pub)
|
||||
defer a.Close()
|
||||
encrypted, _ := a.Encrypt(bigData)
|
||||
// 允许配置信息解密失败时使用原样数据
|
||||
finalData := s.TryDecrypt(configData)
|
||||
// 强制加密场景
|
||||
signature := a.MustSign(data)
|
||||
```
|
||||
|
||||
|
||||
23
README.md
23
README.md
@ -17,9 +17,14 @@
|
||||
### 对称加密 (AES-CBC/GCM)
|
||||
- `func NewAESCBCAndEraseKey(key, iv []byte) (*Symmetric, error)`
|
||||
- `func NewAESGCMAndEraseKey(key, iv []byte) (*Symmetric, error)`
|
||||
- `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)`
|
||||
- `func (s *Symmetric) MustEncrypt(data []byte) []byte`
|
||||
- `func (s *Symmetric) Decrypt(data []byte) (*safe.SafeBuf, error)`
|
||||
- `func (s *Symmetric) DecryptBytes(data []byte) ([]byte, error)`
|
||||
- `func (s *Symmetric) DecryptBytesN(data []byte) []byte` (静默解密)
|
||||
- `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)`
|
||||
@ -28,14 +33,21 @@
|
||||
- `func NewX25519AndEraseKey(priv, pub []byte) (*Asymmetric, error)`
|
||||
- `func NewAsymmetricWithoutEraseKey(algo, priv, pub, fastMode) (*Asymmetric, error)`
|
||||
- `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) Encrypt(data []byte) ([]byte, error)` (混合加密)
|
||||
- `func (a *Asymmetric) Decrypt(data []byte) ([]byte, error)` (混合解密)
|
||||
- `func (a *Asymmetric) MustVerify(data, 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) 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` (新增)
|
||||
- `func Sha256ToHex(d []byte) string` / `func Sha256ToBase64(d []byte) string` / `func Sha256ToUrlBase64(d []byte) string`
|
||||
- *其他算法 (Sha1, Sha512) 均支持上述 Hex/Base64/UrlBase64 变体*
|
||||
|
||||
### 密钥对生成
|
||||
@ -46,6 +58,7 @@
|
||||
|
||||
## 🚀 FastMode 性能模式
|
||||
在高并发服务端对接场景中，内存被恶意扫描的风险极低，但 CPU 压力巨大。
|
||||
Ed25519的非FastMode模式下性能也完全无损，强烈建议优先使用该算法。
|
||||
**建议：** 使用 `NewAsymmetricWithoutEraseKey(..., true)`。
|
||||
* **效果**：缓存解析后的密钥对象。
|
||||
* **性能**：实测签名速度可提升数倍，相比默认模式能支持更高的 QPS。
|
||||
|
||||
@ -15,8 +15,8 @@ func TestRSA_AllModes(t *testing.T) {
|
||||
a, _ := crypto.NewRSAWithOutEraseKey(priv, pub)
|
||||
sig, _ := a.Sign(data)
|
||||
if ok, _ := a.Verify(data, sig); !ok { t.Error("RSA PSS Sign failed") }
|
||||
enc, _ := a.Encrypt(data)
|
||||
dec, _ := a.Decrypt(enc)
|
||||
enc, _ := a.EncryptBytes(data)
|
||||
dec, _ := a.DecryptBytes(enc)
|
||||
if !bytes.Equal(data, dec) { t.Error("RSA OAEP Encrypt failed") }
|
||||
|
||||
// 2. FastMode
|
||||
@ -32,10 +32,10 @@ func TestECDSA_Hybrid(t *testing.T) {
|
||||
a, _ := crypto.NewECDSAndEraseKey(append([]byte(nil), priv...), append([]byte(nil), pub...))
|
||||
|
||||
// Test Hybrid Encrypt (ECDH + AESGCM)
|
||||
enc, err := a.Encrypt(data)
|
||||
enc, err := a.EncryptBytes(data)
|
||||
if err != nil { t.Fatal(err) }
|
||||
|
||||
dec, err := a.Decrypt(enc)
|
||||
dec, err := a.DecryptBytes(enc)
|
||||
if err != nil { t.Fatal(err) }
|
||||
|
||||
if !bytes.Equal(data, dec) { t.Error("ECDSA Hybrid roundtrip failed") }
|
||||
@ -50,7 +50,7 @@ func TestEd25519_Simple(t *testing.T) {
|
||||
if ok, _ := a.Verify(data, sig); !ok { t.Error("Ed25519 failed") }
|
||||
|
||||
// Test Negative: Algorithm doesn't support encryption
|
||||
if _, err := a.Encrypt(data); err == nil {
|
||||
if _, err := a.EncryptBytes(data); err == nil {
|
||||
t.Error("Ed25519 should NOT support encryption")
|
||||
}
|
||||
}
|
||||
@ -60,8 +60,8 @@ func TestX25519_Hybrid(t *testing.T) {
|
||||
data := []byte("x25519 data")
|
||||
|
||||
a, _ := crypto.NewX25519WithOutEraseKey(priv, pub)
|
||||
enc, _ := a.Encrypt(data)
|
||||
dec, _ := a.Decrypt(enc)
|
||||
enc, _ := a.EncryptBytes(data)
|
||||
dec, _ := a.DecryptBytes(enc)
|
||||
if !bytes.Equal(data, dec) { t.Error("X25519 roundtrip failed") }
|
||||
}
|
||||
|
||||
@ -76,7 +76,7 @@ func TestAsymmetricErrors(t *testing.T) {
|
||||
|
||||
// Missing both
|
||||
aEmpty, _ := crypto.NewRSAWithOutEraseKey(nil, nil)
|
||||
if _, err := aEmpty.Encrypt([]byte("x")); err == nil {
|
||||
if _, err := aEmpty.EncryptBytes([]byte("x")); err == nil {
|
||||
t.Error("Should fail to encrypt without public key")
|
||||
}
|
||||
}
|
||||
|
||||
@ -37,7 +37,7 @@ func TestAESExhaustive(t *testing.T) {
|
||||
// 2. 损坏密文测试 (应能正常处理 Pkcs5UnPadding 失败)
|
||||
damaged := append([]byte(nil), enc...)
|
||||
damaged[len(damaged)-1] ^= 0xFF
|
||||
decN := aes.DecryptBytesN(damaged)
|
||||
decN := aes.TryDecrypt(damaged)
|
||||
if bytes.Equal(decN, data) {
|
||||
t.Fatal("Security Breach: Damaged ciphertext still returned correct plaintext")
|
||||
}
|
||||
@ -55,15 +55,15 @@ func TestAsymmetricExhaustive(t *testing.T) {
|
||||
rsa, _ := lcrypto.NewRSAndEraseKey(priv, pub)
|
||||
data := []byte("rsa test data")
|
||||
|
||||
enc, _ := rsa.Encrypt(data)
|
||||
dec, _ := rsa.Decrypt(enc)
|
||||
enc, _ := rsa.EncryptBytes(data)
|
||||
dec, _ := rsa.DecryptBytes(enc)
|
||||
if !bytes.Equal(data, dec) { t.Fatal("RSA encryption failed") }
|
||||
|
||||
// ECDSA Hybrid (ECDH + AESGCM)
|
||||
priv2, pub2, _ := lcrypto.GenerateECDSAKeyPair(256)
|
||||
ecdsa, _ := lcrypto.NewECDSAndEraseKey(priv2, pub2)
|
||||
enc2, _ := ecdsa.Encrypt(data)
|
||||
dec2, _ := ecdsa.Decrypt(enc2)
|
||||
enc2, _ := ecdsa.EncryptBytes(data)
|
||||
dec2, _ := ecdsa.DecryptBytes(enc2)
|
||||
if !bytes.Equal(data, dec2) { t.Fatal("ECDSA Hybrid encryption failed") }
|
||||
}
|
||||
|
||||
@ -162,6 +162,6 @@ func BenchmarkX25519_Encrypt(b *testing.B) {
|
||||
data := []byte("performance test data 1kb")
|
||||
b.ResetTimer()
|
||||
for i := 0; i < b.N; i++ {
|
||||
_, _ = x.Encrypt(data)
|
||||
_, _ = x.EncryptBytes(data)
|
||||
}
|
||||
}
|
||||
|
||||
53
new_test.go
Normal file
53
new_test.go
Normal file
@ -0,0 +1,53 @@
|
||||
package crypto_test
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"testing"
|
||||
|
||||
"apigo.cc/go/crypto"
|
||||
)
|
||||
|
||||
func TestMustAndTryMethods(t *testing.T) {
|
||||
// Setup
|
||||
priv, pub, _ := crypto.GenerateRSAKeyPair(2048)
|
||||
a, _ := crypto.NewRSAWithOutEraseKey(priv, pub)
|
||||
data := []byte("secret")
|
||||
|
||||
// Symmetric
|
||||
key := []byte("1234567890123456")
|
||||
iv := []byte("1234567890123456")
|
||||
s, _ := crypto.NewAESGCMWithOutEraseKey(key, iv)
|
||||
encS, _ := s.EncryptBytes(data)
|
||||
|
||||
// Tests
|
||||
if !bytes.Equal(s.MustEncrypt(data), encS) {
|
||||
t.Error("MustEncrypt mismatch")
|
||||
}
|
||||
if !bytes.Equal(s.MustDecrypt(encS), data) {
|
||||
t.Error("MustDecrypt mismatch")
|
||||
}
|
||||
if !bytes.Equal(s.TryDecrypt([]byte("bad")), []byte("bad")) {
|
||||
t.Error("TryDecrypt should return original on error")
|
||||
}
|
||||
|
||||
// Re-encrypt to get fresh ciphertext for asymmetric
|
||||
encA, _ := a.EncryptBytes(data)
|
||||
decA := a.MustDecrypt(encA)
|
||||
if !bytes.Equal(decA, data) {
|
||||
t.Errorf("Asymmetric MustDecrypt mismatch: got %s, want %s", string(decA), string(data))
|
||||
}
|
||||
|
||||
// Test MustEncrypt specifically (e.g. check it works at all)
|
||||
encA2 := a.MustEncrypt(data)
|
||||
decA2 := a.MustDecrypt(encA2)
|
||||
if !bytes.Equal(decA2, data) {
|
||||
t.Errorf("Asymmetric MustEncrypt/Decrypt failed")
|
||||
}
|
||||
|
||||
if !bytes.Equal(a.TryDecrypt([]byte("bad")), []byte("bad")) {
|
||||
t.Error("Asymmetric TryDecrypt should return original on error")
|
||||
}
|
||||
if len(a.MustSign(data)) == 0 {
|
||||
t.Error("MustSign failed")
|
||||
}
|
||||
}
|
||||
@ -39,7 +39,7 @@ func TestSymmetricPadding(t *testing.T) {
|
||||
// 模拟损坏密文导致填充错误
|
||||
damaged := append([]byte(nil), enc...)
|
||||
damaged[len(damaged)-1] ^= 0xFF
|
||||
if d := aes.DecryptBytesN(damaged); bytes.Equal(d, data) {
|
||||
if d := aes.TryDecrypt(damaged); bytes.Equal(d, data) {
|
||||
t.Error("Should detect padding error in damaged ciphertext")
|
||||
}
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user