first commit

pkg/lzkit/crypto/README.md

@@ -0,0 +1,235 @@
+# AES 加密工具包
+
+本包提供了多种加密方式，特别是用于处理敏感个人信息(如手机号、身份证号等)的加密和解密功能。
+
+## 主要功能
+
+-   **AES-CBC 模式加密/解密** - 标准加密模式，适用于一般数据加密
+-   **AES-ECB 模式加密/解密** - 确定性加密模式，适用于数据库字段加密和查询
+-   **专门针对个人敏感信息的加密/解密方法**
+-   **密钥生成和管理工具**
+
+## 安全性说明
+
+-   **AES-CBC 模式**：使用随机 IV，相同明文每次加密结果不同，安全性较高
+-   **AES-ECB 模式**：确定性加密，相同明文每次加密结果相同，便于数据库查询，但安全性较低
+
+> **⚠️ 警告**：ECB 模式仅适用于短文本(如手机号、身份证号)的确定性加密，不建议用于加密大段文本或高安全需求场景。
+
+## 使用示例
+
+### 1. 加密手机号
+
+使用 AES-ECB 模式加密手机号，保证确定性(相同手机号总是产生相同密文)：
+
+```go
+import (
+    "fmt"
+    "hm-server/pkg/lzkit/crypto"
+)
+
+func encryptMobileExample() {
+    // 您的密钥(需安全保存，建议存储在配置中)
+    key := []byte("1234567890abcdef") // 16字节AES-128密钥
+
+    // 加密手机号
+    mobile := "13800138000"
+    encryptedMobile, err := crypto.EncryptMobile(mobile, key)
+    if err != nil {
+        panic(err)
+    }
+
+    fmt.Println("加密后的手机号:", encryptedMobile)
+
+    // 解密手机号
+    decryptedMobile, err := crypto.DecryptMobile(encryptedMobile, key)
+    if err != nil {
+        panic(err)
+    }
+
+    fmt.Println("解密后的手机号:", decryptedMobile)
+}
+```
+
+### 2. 在数据库中存储和查询加密手机号
+
+```go
+// 加密并存储手机号
+func saveUser(db *sqlx.DB, mobile string, key []byte) (int64, error) {
+    encryptedMobile, err := crypto.EncryptMobile(mobile, key)
+    if err != nil {
+        return 0, err
+    }
+
+    var id int64
+    err = db.QueryRow(
+        "INSERT INTO users (mobile, create_time) VALUES (?, NOW()) RETURNING id",
+        encryptedMobile,
+    ).Scan(&id)
+
+    return id, err
+}
+
+// 根据手机号查询用户
+func findUserByMobile(db *sqlx.DB, mobile string, key []byte) (*User, error) {
+    encryptedMobile, err := crypto.EncryptMobile(mobile, key)
+    if err != nil {
+        return nil, err
+    }
+
+    var user User
+    err = db.QueryRow(
+        "SELECT id, mobile, create_time FROM users WHERE mobile = ?",
+        encryptedMobile,
+    ).Scan(&user.ID, &user.EncryptedMobile, &user.CreateTime)
+
+    if err != nil {
+        return nil, err
+    }
+
+    // 解密手机号用于显示
+    user.Mobile, _ = crypto.DecryptMobile(user.EncryptedMobile, key)
+
+    return &user, nil
+}
+```
+
+### 3. 加密身份证号
+
+```go
+func encryptIDCardExample() {
+    key := []byte("1234567890abcdef")
+
+    idCard := "440101199001011234"
+    encryptedIDCard, err := crypto.EncryptIDCard(idCard, key)
+    if err != nil {
+        panic(err)
+    }
+
+    fmt.Println("加密后的身份证号:", encryptedIDCard)
+
+    // 解密身份证号
+    decryptedIDCard, err := crypto.DecryptIDCard(encryptedIDCard, key)
+    if err != nil {
+        panic(err)
+    }
+
+    fmt.Println("解密后的身份证号:", decryptedIDCard)
+}
+```
+
+### 4. 密钥管理
+
+```go
+func keyManagementExample() {
+    // 生成随机密钥
+    key, err := crypto.GenerateAESKey(16) // AES-128
+    if err != nil {
+        panic(err)
+    }
+    fmt.Printf("生成的密钥(十六进制): %x\n", key)
+
+    // 从密码派生密钥(便于记忆)
+    password := "my-secure-password"
+    derivedKey, err := crypto.DeriveKeyFromPassword(password, 16)
+    if err != nil {
+        panic(err)
+    }
+    fmt.Printf("从密码派生的密钥: %x\n", derivedKey)
+}
+```
+
+### 5. 使用十六进制输出(适用于 URL 参数)
+
+```go
+func hexEncodingExample() {
+    key := []byte("1234567890abcdef")
+    mobile := "13800138000"
+
+    // 使用十六进制编码(适合URL参数)
+    encryptedHex, err := crypto.EncryptMobileHex(mobile, key)
+    if err != nil {
+        panic(err)
+    }
+
+    fmt.Println("十六进制编码的加密手机号:", encryptedHex)
+
+    // 解密十六进制编码的手机号
+    decryptedMobile, err := crypto.DecryptMobileHex(encryptedHex, key)
+    if err != nil {
+        panic(err)
+    }
+
+    fmt.Println("解密后的手机号:", decryptedMobile)
+}
+```
+
+## 在 Go-Zero 项目中使用
+
+在 Go-Zero 项目中，建议将加密密钥放在配置文件中：
+
+1. 在配置文件中添加密钥配置：
+
+```yaml
+# etc/main.yaml
+Name: main-api
+Host: 0.0.0.0
+Port: 8888
+
+Encrypt:
+    MobileKey: "1234567890abcdef" # 16字节AES-128密钥
+    IDCardKey: "1234567890abcdef1234567890abcdef" # 32字节AES-256密钥
+```
+
+2. 在配置结构中定义：
+
+```go
+type Config struct {
+    rest.RestConf
+    Encrypt struct {
+        MobileKey string
+        IDCardKey string
+    }
+}
+```
+
+3. 在服务上下文中使用：
+
+```go
+type ServiceContext struct {
+    Config      config.Config
+    UserModel   model.UserModel
+    MobileKey   []byte
+    IDCardKey   []byte
+}
+
+func NewServiceContext(c config.Config) *ServiceContext {
+    return &ServiceContext{
+        Config:      c,
+        UserModel:   model.NewUserModel(sqlx.NewMysql(c.DB.DataSource), c.Cache),
+        MobileKey:   []byte(c.Encrypt.MobileKey),
+        IDCardKey:   []byte(c.Encrypt.IDCardKey),
+    }
+}
+```
+
+4. 在 Logic 中使用：
+
+```go
+func (l *RegisterLogic) Register(req *types.RegisterReq) (*types.RegisterResp, error) {
+    // 加密手机号用于存储
+    encryptedMobile, err := crypto.EncryptMobile(req.Mobile, l.svcCtx.MobileKey)
+    if err != nil {
+        return nil, errors.New("手机号加密失败")
+    }
+
+    // 保存到数据库
+    user := &model.User{
+        Mobile: encryptedMobile,
+        // 其他字段...
+    }
+
+    result, err := l.svcCtx.UserModel.Insert(l.ctx, nil, user)
+    // 其余逻辑...
+}
+```