# 加密解密 API

<cite>
**本文档引用的文件**
- [TsCrypto.js](file://src/utils/TsCrypto.js)
- [TsSM4.js](file://src/utils/TsSM4.js)
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
- [index.js](file://index.js)
- [package.json](file://package.json)
- [README.md](file://README.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介

本项目是一个基于 SM4 对称加密算法的 JavaScript 加密解密工具包。该工具包提供了完整的加密解密功能，支持 ECB 和 CBC 两种加密模式，内置 Base64 编解码处理，并集成了 HTTP 请求加密传输功能。系统采用模块化设计，通过 TsCrypto 类封装 SM4 加密算法，通过 TsSM4 类实现具体的 SM4 算法逻辑，通过 TsHttpUtil 类实现 HTTP 请求的自动加密功能。

## 项目结构

该项目采用模块化组织结构，主要包含以下核心模块：

```mermaid
graph TB
subgraph "核心模块"
Crypto[TsCrypto.js<br/>加密器封装]
SM4[TsSM4.js<br/>SM4算法实现]
Config[TsGlobalConfig.js<br/>全局配置]
end
subgraph "工具模块"
Http[TsHttpUtil.js<br/>HTTP请求工具]
Storage[TsStorage.js<br/>本地存储]
Common[TsCommon.js<br/>通用工具]
end
subgraph "外部依赖"
Base64[base64-js<br/>Base64编解码]
UmiRequest[umi-request<br/>HTTP请求库]
end
Crypto --> SM4
Crypto --> Config
Http --> Crypto
Http --> Storage
Http --> Config
SM4 --> Base64
Http --> UmiRequest
```

**图表来源**
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)

**章节来源**
- [index.js:1-16](file://index.js#L1-L16)
- [package.json:19-22](file://package.json#L19-L22)

## 核心组件

### TsCrypto 加密器

TsCrypto 是整个加密系统的核心封装类，负责提供简化的加密解密接口。它内部使用 TsSM4 类来执行实际的加密解密操作。

**主要特性：**
- 基于 SM4 算法的对称加密
- 内置 Base64 编解码处理
- 支持 ECB 和 CBC 模式配置
- 自动密钥管理

**章节来源**
- [TsCrypto.js:5-34](file://src/utils/TsCrypto.js#L5-L34)

### TsSM4 SM4 算法实现

TsSM4 类实现了完整的 SM4 对称加密算法，包括密钥扩展、加密轮函数、填充和去填充等功能。

**核心功能：**
- 完整的 SM4 算法实现
- 支持 ECB 和 CBC 两种模式
- 自动填充和去填充机制
- Base64 和文本两种输出格式

**章节来源**
- [TsSM4.js:96-456](file://src/utils/TsSM4.js#L96-L456)

### TsGlobalConfig 全局配置

提供全局配置管理功能，支持动态设置和获取加密密钥、HTTP 前缀等配置项。

**配置选项：**
- base64Key: Base64 编码的密钥字符串
- prefix: HTTP 请求前缀
- onHttpError: HTTP 错误回调函数
- httpParams: HTTP 参数处理函数

**章节来源**
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)

## 架构概览

系统采用分层架构设计，从上到下分为应用层、工具层、算法层和依赖层：

```mermaid
graph TB
subgraph "应用层"
App[业务应用]
end
subgraph "工具层"
HttpUtil[TsHttpUtil<br/>HTTP请求工具]
Crypto[TsCrypto<br/>加密器]
Storage[TsStorage<br/>存储工具]
end
subgraph "算法层"
SM4[TsSM4<br/>SM4算法]
Crypt[TsCrypt<br/>编解码工具]
end
subgraph "依赖层"
Base64[base64-js]
UmiRequest[umi-request]
end
App --> HttpUtil
App --> Crypto
HttpUtil --> Crypto
Crypto --> SM4
SM4 --> Crypt
SM4 --> Base64
HttpUtil --> UmiRequest
```

**图表来源**
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)

## 详细组件分析

### TsCrypto 类详细分析

TsCrypto 类提供了简洁的加密解密接口，内部封装了复杂的加密细节。

#### 类结构图

```mermaid
classDiagram
class TsCrypto {
-sm4 : SM4
+constructor()
+encrypt(content) : string
+decrypt(base64) : string
}
class SM4 {
-key : Uint8Array
-iv : Uint8Array
-mode : string
-cipherType : string
-encryptRoundKeys : Uint32Array
-decryptRoundKeys : Uint32Array
+constructor(config)
+encrypt(plaintext) : string
+decrypt(ciphertext) : string
}
class Crypt {
+stringToArrayBufferInUtf8(str) : Uint8Array
+utf8ArrayBufferToString(buffer) : string
+arrayBufferToBase64(buffer) : string
+base64ToArrayBuffer(base64) : Uint8Array
}
TsCrypto --> SM4 : "组合"
SM4 --> Crypt : "使用"
```

**图表来源**
- [TsCrypto.js:5-34](file://src/utils/TsCrypto.js#L5-L34)
- [TsSM4.js:96-456](file://src/utils/TsSM4.js#L96-L456)

#### 加密流程序列图

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Crypto as "TsCrypto"
participant SM4 as "TsSM4"
participant Crypt as "Crypt"
Client->>Crypto : encrypt(明文)
Crypto->>SM4 : encrypt(明文)
SM4->>Crypt : stringToArrayBufferInUtf8(明文)
Crypt-->>SM4 : Uint8Array
SM4->>SM4 : padding(填充)
SM4->>SM4 : doBlockCrypt(加密块)
SM4->>Crypt : arrayBufferToBase64(密文)
Crypt-->>SM4 : Base64字符串
SM4-->>Crypto : Base64密文
Crypto-->>Client : 返回密文
```

**图表来源**
- [TsCrypto.js:19-21](file://src/utils/TsCrypto.js#L19-L21)
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)

**章节来源**
- [TsCrypto.js:15-30](file://src/utils/TsCrypto.js#L15-L30)

### TsSM4 类详细分析

TsSM4 类实现了完整的 SM4 算法，包括密钥扩展、加密轮函数和填充机制。

#### 算法流程图

```mermaid
flowchart TD
Start([开始加密]) --> ValidateKey["验证密钥长度(16字节)"]
ValidateKey --> CheckMode{"检查加密模式"}
CheckMode --> |CBC| InitIV["初始化IV(16字节)"]
CheckMode --> |ECB| NoIV["无IV模式"]
InitIV --> PadData["数据填充(PKCS7)"]
NoIV --> PadData
PadData --> SplitBlocks["分割为16字节块"]
SplitBlocks --> EncryptLoop{"遍历每个数据块"}
EncryptLoop --> |CBC模式| CBCProcess["CBC处理:<br/>异或链+加密"]
EncryptLoop --> |ECB模式| ECBProcess["ECB处理:<br/>直接加密"]
CBCProcess --> NextBlock{"还有下一个块?"}
ECBProcess --> NextBlock
NextBlock --> |是| EncryptLoop
NextBlock --> |否| EncodeOutput["编码输出(Base64)"]
EncodeOutput --> End([结束])
```

**图表来源**
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
- [TsSM4.js:343-378](file://src/utils/TsSM4.js#L343-L378)

#### 关键算法实现

**密钥扩展算法：**
- 使用 FK 常量和 CK 数组
- 生成 32 轮加密密钥
- 每轮密钥长度 32 位

**加密轮函数：**
- 实现 τ 变换和线性变换
- 包含 S 盒替换
- 支持 32 轮加密

**填充机制：**
- 使用 PKCS7 填充标准
- 自动处理任意长度数据
- 支持去填充操作

**章节来源**
- [TsSM4.js:189-207](file://src/utils/TsSM4.js#L189-L207)
- [TsSM4.js:250-278](file://src/utils/TsSM4.js#L250-L278)
- [TsSM4.js:287-312](file://src/utils/TsSM4.js#L287-L312)

### HTTP 加密传输集成

TsHttpUtil 类集成了加密功能，实现了 HTTP 请求的自动加密传输。

#### 加密传输流程

```mermaid
sequenceDiagram
participant App as "应用"
participant HttpUtil as "TsHttpUtil"
participant Crypto as "TsCrypto"
participant Server as "服务器"
App->>HttpUtil : post(url, data)
HttpUtil->>HttpUtil : dealParamsBody()
HttpUtil->>HttpUtil : 检查是否启用加密
HttpUtil->>Crypto : encrypt(JSON.stringify(data))
Crypto-->>HttpUtil : Base64密文
HttpUtil->>Server : POST /api/data {encryptData : 密文}
Server-->>HttpUtil : {code : 200, data : 明文}
HttpUtil->>HttpUtil : 检查响应是否加密
HttpUtil->>Crypto : decrypt(响应数据)
Crypto-->>HttpUtil : 明文数据
HttpUtil-->>App : 返回解析后的数据
```

**图表来源**
- [TsHttpUtil.js:82-87](file://src/https/TsHttpUtil.js#L82-L87)
- [TsHttpUtil.js:119-122](file://src/https/TsHttpUtil.js#L119-L122)

**章节来源**
- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)

## 依赖关系分析

### 外部依赖

项目的主要外部依赖包括：

| 依赖包 | 版本 | 用途 |
|--------|------|------|
| base64-js | 1.5.1 | Base64 编解码处理 |
| umi-request | 1.4.0 | HTTP 请求库 |

### 内部模块依赖

```mermaid
graph LR
index[index.js<br/>入口文件] --> TsCrypto[TsCrypto.js]
index --> TsSM4[TsSM4.js]
index --> TsGlobalConfig[TsGlobalConfig.js]
index --> TsHttpUtil[TsHttpUtil.js]
TsCrypto --> TsSM4
TsCrypto --> TsGlobalConfig
TsHttpUtil --> TsCrypto
TsHttpUtil --> TsStorage
TsHttpUtil --> TsCommon
TsHttpUtil --> TsGlobalConfig
```

**图表来源**
- [index.js:1-16](file://index.js#L1-L16)
- [package.json:19-22](file://package.json#L19-L22)

**章节来源**
- [package.json:19-22](file://package.json#L19-L22)
- [index.js:1-16](file://index.js#L1-L16)

## 性能考虑

### 加密性能优化

1. **内存管理**：
   - 使用 TypedArray 进行高效的数据处理
   - 避免不必要的数据拷贝
   - 合理使用缓冲区复用

2. **算法优化**：
   - 采用 32 位整数运算提高性能
   - 使用预计算的 S 盒表
   - 优化循环结构减少开销

3. **I/O 优化**：
   - Base64 编解码使用高效的库实现
   - 批量处理数据块避免频繁调用

### 安全性最佳实践

1. **密钥管理**：
   - 密钥必须为 16 字节长度
   - 建议使用安全的随机数生成器
   - 定期更换密钥

2. **模式选择**：
   - CBC 模式提供更好的安全性
   - ECB 模式仅适用于相同明文的场景
   - IV 必须随机且唯一

3. **填充安全**：
   - 使用标准的 PKCS7 填充
   - 验证去填充结果的有效性

## 故障排除指南

### 常见错误及解决方案

**密钥长度错误**
- 错误信息：`key should be a 16 bytes string`
- 解决方案：确保密钥为 16 字节长度的 Base64 编码

**IV 初始化错误**
- 错误信息：`iv error`
- 解决方案：在 CBC 模式下提供 16 字节长度的 IV

**数据解密失败**
- 可能原因：密钥不匹配、数据损坏
- 解决方案：验证密钥正确性，检查数据完整性

**Base64 编码问题**
- 可能原因：输入数据格式不正确
- 解决方案：确保输入为有效的字符串或 Buffer

### 调试技巧

1. **启用开发模式**：
   ```javascript
   // 在开发环境中启用详细日志
   const isDev = TsCommon.isDevelopment();
   ```

2. **验证加密结果**：
   ```javascript
   const original = "测试数据";
   const encrypted = TsCrypto.encrypt(original);
   const decrypted = TsCrypto.decrypt(encrypted);
   console.assert(original === decrypted, "加密解密结果不匹配");
   ```

**章节来源**
- [TsSM4.js:103-105](file://src/utils/TsSM4.js#L103-L105)
- [TsSM4.js:119-121](file://src/utils/TsSM4.js#L119-L121)
- [TsSM4.js:346](file://src/utils/TsSM4.js#L346)

## 结论

本加密解密模块提供了完整的 SM4 对称加密解决方案，具有以下特点：

1. **功能完整**：支持 ECB 和 CBC 两种加密模式，提供 Base64 编解码
2. **易于使用**：提供简洁的 API 接口，便于集成到现有项目中
3. **安全可靠**：采用标准的 SM4 算法和 PKCS7 填充机制
4. **性能优化**：使用高效的 TypedArray 和优化的算法实现

该模块特别适合需要数据加密传输和存储的应用场景，如 API 数据传输、用户敏感信息存储等。通过合理的配置和使用，可以有效提升应用程序的安全性。