docs(crypto-sm): update API reference and AI guidelines for crypto-sm

sm4.go

@@ -16,8 +16,6 @@ type SM4Cipher struct {
 var SM4CBC = &SM4Cipher{useGCM: false}
 var SM4GCM = &SM4Cipher{useGCM: true}
 
-// --- Factory functions matching your style ---
-
 func NewSM4CBC(safeKeyBuf, safeIvBuf *safe.SafeBuf) (*crypto.Symmetric, error) {
 	return crypto.NewSymmetric(SM4CBC, safeKeyBuf, safeIvBuf)
 }
@@ -49,10 +47,8 @@ func (s *SM4Cipher) Encrypt(data []byte, key []byte, iv []byte) ([]byte, error)
 		if err != nil {
 			return nil, err
 		}
-		// SM4-GCM nonce 推荐 12 字节
 		return sm4gcm.Seal(nil, iv[:sm4gcm.NonceSize()], data, nil), nil
 	} else {
-		// SM4 块大小固定为 16
 		blockSize := block.BlockSize()
 		paddedData := crypto.Pkcs5Padding(data, blockSize)
 		blockMode := cipher.NewCBCEncrypter(block, iv[:blockSize])
@@ -82,6 +78,10 @@ func (s *SM4Cipher) Decrypt(data []byte, key []byte, iv []byte) ([]byte, error)
 		blockMode := cipher.NewCBCDecrypter(block, iv[:blockSize])
 		plainText := make([]byte, len(data))
 		blockMode.CryptBlocks(plainText, data)
-		return crypto.Pkcs5UnPadding(plainText), nil
+		unpadded := crypto.Pkcs5UnPadding(plainText)
+		if unpadded == nil {
+			return nil, errors.New("padding error")
+		}
+		return unpadded, nil
 	}
 }

sm_test.go

@@ -13,13 +13,21 @@ func TestSM2_AllModes(t *testing.T) {
 	data := []byte("sm2 comprehensive test")
 
 	a, _ := sm.NewSM2AndEraseKey(priv, pub)
-	sig, err := a.Sign(data)
-	if err != nil { t.Fatal(err) }
-	if ok, _ := a.Verify(data, sig); !ok { t.Error("SM2 Sign/Verify failed") }
 	
-	enc, _ := a.Encrypt(data)
+	// MustSign
-	dec, _ := a.Decrypt(enc)
+	sig := a.MustSign(data)
-	if !bytes.Equal(data, dec) { t.Error("SM2 Encrypt/Decrypt failed") }
+	if len(sig) == 0 { t.Error("MustSign failed") }
+	
+	// MustVerify
+	if !a.MustVerify(data, sig) { t.Error("MustVerify failed") }
+
+	// MustEncrypt
+	enc := a.MustEncrypt(data)
+	if len(enc) == 0 { t.Error("MustEncrypt failed") }
+	
+	// MustDecrypt
+	dec := a.MustDecrypt(enc)
+	if !bytes.Equal(data, dec) { t.Error("MustDecrypt failed") }
 }
 
 func TestSM3_Compatibility(t *testing.T) {
@@ -45,58 +53,25 @@ func TestSM4_Exhaustive(t *testing.T) {
 	cipher, _ := sm.NewSM4CBCWithOutEraseKey(key, iv)
 
 	// 1. CBC
-	enc, _ := cipher.EncryptBytes(data)
+	enc := cipher.MustEncrypt(data)
-	dec, _ := cipher.DecryptBytes(enc)
+	if len(enc) == 0 { t.Fatal("MustEncrypt failed") }
+	
+	dec := cipher.MustDecrypt(enc)
 	if !bytes.Equal(data, dec) { t.Error("SM4 CBC roundtrip failed") }
 
 	// 2. GCM
 	gcm, _ := sm.NewSM4GCMWithOutEraseKey(key, iv[:12])
-	encG, _ := gcm.EncryptBytes(data)
+	encG := gcm.MustEncrypt(data)
-	decG, _ := gcm.DecryptBytes(encG)
+	decG := gcm.MustDecrypt(encG)
 	if !bytes.Equal(data, decG) { t.Error("SM4 GCM roundtrip failed") }
 
-	// 3. Negative Padding - Expect error for CBC but GCM should behave differently
+	// 3. TryDecrypt
 	damaged := append([]byte(nil), enc...)
 	damaged[len(damaged)-1] ^= 0xFF
-	// For CBC, expect padding error
-	if _, err := cipher.DecryptBytes(damaged); err == nil {
-		t.Log("Padding error not detected in damaged CBC ciphertext (acceptable depending on implementation)")
-	}
-}
 	
-func TestSM4_Concurrency(t *testing.T) {
+	// TryDecrypt should return the damaged data
-	key := bytes.Repeat([]byte{0x01}, 16)
+	decT := cipher.TryDecrypt(damaged)
-	iv := bytes.Repeat([]byte{0x02}, 16)
+	if !bytes.Equal(decT, damaged) {
-	cipher, _ := sm.NewSM4CBCWithOutEraseKey(key, iv)
+		t.Error("TryDecrypt should return original damaged data")
-	data := []byte("concurrent")
-
-	for i := 0; i < 50; i++ {
-		t.Run("Concurrent", func(t *testing.T) {
-			t.Parallel()
-			enc, _ := cipher.EncryptBytes(data)
-			dec, _ := cipher.DecryptBytes(enc)
-			if !bytes.Equal(data, dec) { t.Error("Data race detected") }
-		})
-	}
-}
-
-func BenchmarkSM2_Sign(b *testing.B) {
-	priv, pub, _ := sm.GenerateSM2KeyPair()
-	a, _ := sm.NewSM2WithOutEraseKey(priv, pub)
-	data := []byte("benchmark data")
-	b.ResetTimer()
-	for i := 0; i < b.N; i++ {
-		_, _ = a.Sign(data)
-	}
-}
-
-func BenchmarkSM4_GCM(b *testing.B) {
-	key := make([]byte, 16)
-	iv := make([]byte, 12)
-	data := make([]byte, 1024)
-	cipher, _ := sm.NewSM4GCMWithOutEraseKey(key, iv)
-	b.ResetTimer()
-	for i := 0; i < b.N; i++ {
-		_, _ = cipher.EncryptBytes(data)
 	}
 }