# iOS端加密对接指南

## 概述

本文档描述了如何在iOS端实现与服务端兼容的AES-256-GCM加解密功能。

## 加密规格

- **算法**: AES-256-GCM
- **密钥长度**: 256位 (32字节)
- **IV长度**: 96位 (12字节)
- **认证标签长度**: 128位 (16字节)
- **数据格式**: Base64编码的 `IV + AuthTag + Ciphertext`

## 环境变量配置

在服务端设置环境变量 `ENCRYPTION_KEY`，确保密钥安全：

```bash
export ENCRYPTION_KEY="your-32-character-secret-key-here"
```

## iOS Swift 实现

### 1. 创建加密工具类

```swift
import Foundation
import CryptoKit

class EncryptionHelper {
    private static let keyLength = 32
    private static let ivLength = 12
    private static let tagLength = 16
    private static let additionalData = "additional-data".data(using: .utf8)!

    // 从配置或钥匙串获取密钥
    private static let encryptionKey: SymmetricKey = {
        let keyString = "your-32-character-secret-key-here" // 应从安全存储获取
        let keyData = keyString.prefix(keyLength).padding(toLength: keyLength, withPad: "0", startingAt: 0).data(using: .utf8)!
        return SymmetricKey(data: keyData)
    }()

    /// 加密数据
    /// - Parameter plaintext: 要加密的明文字符串
    /// - Returns: Base64编码的加密数据，格式：iv + tag + ciphertext
    static func encrypt(_ plaintext: String) throws -> String {
        guard let data = plaintext.data(using: .utf8) else {
            throw EncryptionError.invalidInput
        }

        // 生成随机IV
        let iv = Data((0..<ivLength).map { _ in UInt8.random(in: 0...255) })

        // 使用AES-GCM加密
        let sealedBox = try AES.GCM.seal(data, using: encryptionKey, nonce: AES.GCM.Nonce(data: iv), authenticating: additionalData)

        // 组合数据：IV + Tag + Ciphertext
        var combined = Data()
        combined.append(iv)
        combined.append(sealedBox.tag)
        combined.append(sealedBox.ciphertext)

        return combined.base64EncodedString()
    }

    /// 解密数据
    /// - Parameter encryptedData: Base64编码的加密数据
    /// - Returns: 解密后的明文字符串
    static func decrypt(_ encryptedData: String) throws -> String {
        guard let combined = Data(base64Encoded: encryptedData) else {
            throw EncryptionError.invalidInput
        }

        guard combined.count >= ivLength + tagLength else {
            throw EncryptionError.invalidDataLength
        }

        // 提取各部分
        let iv = combined.prefix(ivLength)
        let tag = combined.dropFirst(ivLength).prefix(tagLength)
        let ciphertext = combined.dropFirst(ivLength + tagLength)

        // 创建密封盒进行解密
        let sealedBox = try AES.GCM.SealedBox(nonce: AES.GCM.Nonce(data: iv), ciphertext: ciphertext, tag: tag)
        let decryptedData = try AES.GCM.open(sealedBox, using: encryptionKey, authenticating: additionalData)

        guard let plaintext = String(data: decryptedData, encoding: .utf8) else {
            throw EncryptionError.decodingFailed
        }

        return plaintext
    }
}

enum EncryptionError: Error {
    case invalidInput
    case invalidDataLength
    case decodingFailed
}
```

### 2. 使用示例

```swift
// 创建用户数据
struct CreateUserRequest: Codable {
    let id: String
    let name: String
    let mail: String
}

// 加密请求体
struct EncryptedRequest: Codable {
    let encryptedData: String
}

// 加密响应体
struct EncryptedResponse: Codable {
    let success: Bool
    let message: String
    let encryptedData: String?
}

// 使用示例
func createUserWithEncryption() async {
    do {
        // 1. 准备用户数据
        let userData = CreateUserRequest(
            id: "1234567890",
            name: "张三",
            mail: "zhangsan@example.com"
        )

        // 2. 序列化为JSON
        let jsonData = try JSONEncoder().encode(userData)
        let jsonString = String(data: jsonData, encoding: .utf8)!

        // 3. 加密数据
        let encryptedData = try EncryptionHelper.encrypt(jsonString)

        // 4. 创建请求体
        let request = EncryptedRequest(encryptedData: encryptedData)

        // 5. 发送请求
        let response = try await sendEncryptedRequest(request)

        // 6. 解密响应（如果有加密数据）
        if let encryptedResponseData = response.encryptedData {
            let decryptedResponse = try EncryptionHelper.decrypt(encryptedResponseData)
            print("解密后的响应: \(decryptedResponse)")
        }

    } catch {
        print("加密通信失败: \(error)")
    }
}

func sendEncryptedRequest(_ request: EncryptedRequest) async throws -> EncryptedResponse {
    let url = URL(string: "https://your-server.com/users/encrypted")!
    var urlRequest = URLRequest(url: url)
    urlRequest.httpMethod = "POST"
    urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")

    let requestData = try JSONEncoder().encode(request)
    urlRequest.httpBody = requestData

    let (data, _) = try await URLSession.shared.data(for: urlRequest)
    return try JSONDecoder().decode(EncryptedResponse.self, from: data)
}
```

## API 接口

### 加密版创建用户接口

**端点**: `POST /users/encrypted`

**请求体**:

```json
{
  "encryptedData": "base64编码的加密数据"
}
```

**响应体**:

```json
{
  "success": true,
  "message": "用户创建成功",
  "encryptedData": "base64编码的加密响应数据"
}
```

## 安全建议

1. **密钥管理**:

   - 生产环境必须使用环境变量或安全密钥管理服务
   - iOS端应将密钥存储在钥匙串中
   - 定期轮换密钥

2. **传输安全**:

   - 始终使用HTTPS
   - 考虑添加请求签名验证

3. **错误处理**:

   - 不要在错误信息中暴露加密细节
   - 记录加密失败日志用于监控

4. **测试**:
   - 确保iOS端和服务端使用相同的密钥
   - 测试各种边界情况和错误场景

## 故障排除

1. **解密失败**: 检查密钥是否一致
2. **格式错误**: 确认Base64编码格式正确
3. **数据长度错误**: 验证IV和Tag长度是否正确