# SM4 算法模块 (TsSM4)

<cite>
**本文档引用的文件**
- [TsSM4.js](file://src/utils/TsSM4.js)
- [TsCrypto.js](file://src/utils/TsCrypto.js)
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.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 算法模块是基于中国国家密码标准的对称加密算法实现，采用 128 位分组长度和 128 位密钥长度。该模块提供了完整的 SM4 加密解密功能，支持 CBC 和 ECB 两种工作模式，并实现了 PKCS7 自动填充算法。模块设计遵循现代 JavaScript 最佳实践，使用 ES6 类语法和 TypedArray 数据结构，确保高性能和内存效率。

本模块在企业级应用中用于数据加密、安全通信和敏感信息保护，特别适用于需要符合中国国家标准的加密需求场景。

## 项目结构

该项目采用模块化组织方式，主要包含以下核心文件：

```mermaid
graph TB
subgraph "核心模块"
SM4[TsSM4.js<br/>主加密模块]
Crypto[TsCrypto.js<br/>加密服务封装]
Global[TsGlobalConfig.js<br/>全局配置]
end
subgraph "工具模块"
Common[TsCommon.js<br/>通用工具]
Storage[TsStorage.js<br/>存储工具]
HttpUtil[TsHttpUtil.js<br/>HTTP工具]
end
subgraph "入口文件"
Index[index.js<br/>模块导出]
Package[package.json<br/>依赖管理]
end
SM4 --> Crypto
Crypto --> Global
Index --> SM4
Index --> Crypto
Index --> Common
Index --> Storage
Index --> HttpUtil
Package --> SM4
Package --> Crypto
```

**图表来源**
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
- [index.js:1-16](file://index.js#L1-L16)

**章节来源**
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
- [index.js:1-16](file://index.js#L1-L16)

## 核心组件

### 主要类结构

TsSM4 模块包含两个核心类：Crypt 工具类和 TsSM4 加密类。

```mermaid
classDiagram
class Crypt {
+stringToArrayBufferInUtf8(str) Uint8Array
+utf8ArrayBufferToString(buffer) String
+arrayBufferToBase64(buffer) String
+base64ToArrayBuffer(base64) Uint8Array
}
class TsSM4 {
-Uint8Array key
-Uint8Array iv
-String mode
-String cipherType
-Uint32Array encryptRoundKeys
-Uint32Array decryptRoundKeys
+constructor(config)
+doBlockCrypt(blockData, roundKeys) Uint32Array
+spawnEncryptRoundKeys() Uint32Array
+rotateLeft(x, y) Number
+linearTransform1(b) Number
+linearTransform2(b) Number
+tauTransform(a) Number
+tTransform1(z) Number
+tTransform2(z) Number
+padding(originalBuffer) Uint8Array
+dePadding(paddedBuffer) Uint8Array
+uint8ToUint32Block(uint8Array, baseIndex) Uint32Array
+encrypt(plaintext) String
+decrypt(ciphertext) String
}
class TsCrypto {
-SM4 sm4
+constructor()
+encrypt(content) String
+decrypt(base64) String
}
TsSM4 --> Crypt : "使用"
TsCrypto --> TsSM4 : "封装"
```

**图表来源**
- [TsSM4.js:39-453](file://src/utils/TsSM4.js#L39-L453)
- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)

### 关键常量定义

模块定义了 SM4 算法的核心常量：

- **Sbox 替换表**: 16×16 的 S 盒替换表，用于字节替换操作
- **CK 常量数组**: 32 个轮常量，用于密钥扩展
- **FK 固定常量**: 4 个固定常量，用于初始密钥处理

**章节来源**
- [TsSM4.js:5-37](file://src/utils/TsSM4.js#L5-L37)

## 架构概览

### 整体架构设计

```mermaid
graph TB
subgraph "应用层"
App[业务应用]
Config[配置管理]
end
subgraph "加密服务层"
CryptoService[TsCrypto]
SM4Engine[TsSM4]
end
subgraph "数据转换层"
Base64[Base64 编码]
UTF8[UTF-8 编码]
ByteArray[字节数组]
end
subgraph "底层实现"
SBox[S 盒表]
RoundKeys[轮密钥]
Transform[变换函数]
end
App --> CryptoService
Config --> CryptoService
CryptoService --> SM4Engine
SM4Engine --> Base64
SM4Engine --> UTF8
SM4Engine --> ByteArray
SM4Engine --> SBox
SM4Engine --> RoundKeys
SM4Engine --> Transform
```

**图表来源**
- [TsSM4.js:96-156](file://src/utils/TsSM4.js#L96-L156)
- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)

### 数据流处理

```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 : UTF-8 字节数组
SM4->>SM4 : padding(填充)
SM4->>SM4 : CBC/ECB 模式处理
SM4->>Crypt : arrayBufferToBase64(密文)
Crypt-->>SM4 : Base64 字符串
SM4-->>Crypto : 密文字符串
Crypto-->>Client : 密文字符串
```

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

## 详细组件分析

### SM4 核心算法实现

#### 密钥扩展算法

密钥扩展是 SM4 算法的核心步骤，负责从原始密钥生成 32 个轮密钥。

```mermaid
flowchart TD
Start([开始密钥扩展]) --> ExtractMK["提取 MK 密钥<br/>mk[0..3] = key[0..15]"]
ExtractMK --> InitK["初始化 K 数组<br/>k[0..3] = mk ⊕ FK"]
InitK --> Loop{"循环 i = 0..31"}
Loop --> CalcK["计算 k[i+4] = k[i] ⊕ T(k[i+1] ⊕ k[i+2] ⊕ k[i+3] ⊕ CK[i])"]
CalcK --> SaveKey["保存轮密钥<br/>encryptRoundKeys[i] = k[i+4]"]
SaveKey --> Loop
Loop --> |完成| ReverseKeys["反转密钥顺序<br/>decryptRoundKeys = reverse(encryptRoundKeys)"]
ReverseKeys --> End([结束])
```

**图表来源**
- [TsSM4.js:189-207](file://src/utils/TsSM4.js#L189-L207)

#### 轮函数实现

每个 SM4 轮包含多个变换操作：

```mermaid
flowchart TD
BlockIn[16字节明文块] --> SplitBlock["分割为4个32位字<br/>block[0..3]"]
SplitBlock --> RoundLoop{"i = 0..31"}
RoundLoop --> XOROp["x[i+4] = x[i] ⊕ T(x[i+1] ⊕ x[i+2] ⊕ x[i+3] ⊕ RK[i])"]
XOROp --> RoundLoop
RoundLoop --> |完成| FinalBlock["组合最终块<br/>y[0..3] = x[32..35]"]
FinalBlock --> BlockOut[16字节密文块]
```

**图表来源**
- [TsSM4.js:166-180](file://src/utils/TsSM4.js#L166-L180)

#### 变换函数详解

##### τ 变换 (字节替换)
τ 变换使用 S 盒进行非线性替换：
- 输入: 32位值
- 处理: 将每个字节通过 S 盒查找替换
- 输出: 32位值

##### L 线性变换
L 变换实现位移和异或操作：
- L1: b ⊕ (b <<< 2) ⊕ (b <<< 10) ⊕ (b <<< 18) ⊕ (b <<< 24)
- L2: b ⊕ (b <<< 13) ⊕ (b <<< 23)

##### T 组合变换
T 变换结合 τ 和 L 变换：
- T1: L1(τ(z))
- T2: L2(τ(z))

**章节来源**
- [TsSM4.js:250-277](file://src/utils/TsSM4.js#L250-L277)

### 工作模式实现

#### CBC 模式

CBC (Cipher Block Chaining) 模式提供链式加密：

```mermaid
sequenceDiagram
participant P as 明文块
participant IV as 初始化向量
participant XOR as 异或运算
participant ENC as 加密器
participant C as 密文块
P1->>XOR : 明文1 ⊕ IV
XOR->>ENC : (明文1 ⊕ IV)
ENC-->>C : 密文1
C->>XOR : 密文1 ⊕ 明文2
XOR->>ENC : (密文1 ⊕ 明文2) ⊕ IV
ENC-->>C : 密文2
Note over IV,C : 每次使用前一个密文作为链输入
```

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

#### ECB 模式

ECB (Electronic Codebook) 模式提供独立块加密：

```mermaid
flowchart TD
Plain1[明文块1] --> Encrypt1[独立加密]
Plain2[明文块2] --> Encrypt2[独立加密]
Plain3[明文块3] --> Encrypt3[独立加密]
Encrypt1 --> Cipher1[密文块1]
Encrypt2 --> Cipher2[密文块2]
Encrypt3 --> Cipher3[密文块3]
Note1[相同明文块产生相同密文块]
Note2[无链式依赖]
```

**图表来源**
- [TsSM4.js:368-378](file://src/utils/TsSM4.js#L368-L378)

### PKCS7 填充算法

PKCS7 是一种标准的块填充方案：

```mermaid
flowchart TD
Start([开始填充]) --> CheckNull{"输入为空?"}
CheckNull --> |是| ReturnNull[返回 null]
CheckNull --> |否| CalcPad["计算填充长度<br/>padLen = 16 - (len % 16)"]
CalcPad --> CreateBuffer["创建新缓冲区<br/>长度 = 原长度 + padLen"]
CreateBuffer --> CopyData["复制原数据到新缓冲区"]
CopyData --> FillPad["填充 padLen 个字节<br/>每个字节值为 padLen"]
FillPad --> ReturnBuffer[返回填充后的缓冲区]
ReturnNull --> End([结束])
ReturnBuffer --> End
```

**图表来源**
- [TsSM4.js:287-296](file://src/utils/TsSM4.js#L287-L296)

**章节来源**
- [TsSM4.js:287-312](file://src/utils/TsSM4.js#L287-L312)

### 数据类型转换

#### 字节数组与 32 位整数转换

```mermaid
flowchart TD
Uint8Array[Uint8Array] --> SplitBytes["按字节分割<br/>每4字节组成一个32位整数"]
SplitBytes --> ShiftLeft["左移操作<br/>高位字节 << 24, 16, 8, 0"]
ShiftLeft --> ORCombine["按位或组合<br/>形成32位整数"]
ORCombine --> Uint32Array[Uint32Array]
Uint32Array --> SplitBits["按位拆分<br/>32位整数拆分为4个字节"]
SplitBits --> ShiftRight["右移操作<br/>高位字节 >> 24, 16, 8, 0"]
ShiftRight --> ANDMask["按位与掩码<br/>& 0xFF"]
ANDMask --> Uint8Array[Uint8Array]
```

**图表来源**
- [TsSM4.js:322-329](file://src/utils/TsSM4.js#L322-L329)

**章节来源**
- [TsSM4.js:322-329](file://src/utils/TsSM4.js#L322-L329)

## 依赖关系分析

### 外部依赖

```mermaid
graph TB
subgraph "外部库"
Base64[base64-js@1.5.1<br/>Base64 编解码]
UmiRequest[umi-request@1.4.0<br/>HTTP 请求]
end
subgraph "内部模块"
SM4[TsSM4.js<br/>SM4 加密算法]
Crypto[TsCrypto.js<br/>加密服务封装]
Global[TsGlobalConfig.js<br/>全局配置]
Common[TsCommon.js<br/>通用工具]
Storage[TsStorage.js<br/>存储工具]
HttpUtil[TsHttpUtil.js<br/>HTTP 工具]
end
SM4 --> Base64
Crypto --> Base64
Crypto --> Global
HttpUtil --> UmiRequest
```

**图表来源**
- [package.json:19-22](file://package.json#L19-L22)
- [TsSM4.js](file://src/utils/TsSM4.js#L1)
- [TsCrypto.js](file://src/utils/TsCrypto.js#L1)

### 内部模块依赖

```mermaid
graph LR
SM4[TsSM4] --> Crypt[Crypt 工具类]
Crypto[TsCrypto] --> SM4
Crypto --> Global[全局配置]
HttpUtil[TsHttpUtil] --> SM4
HttpUtil --> Crypto
```

**图表来源**
- [TsSM4.js:1-94](file://src/utils/TsSM4.js#L1-L94)
- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)
- [index.js:1-16](file://index.js#L1-L16)

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

## 性能考虑

### 内存使用分析

#### 数据结构内存占用

| 数据结构 | 大小 | 用途 |
|---------|------|------|
| Uint8Array | 1 字节/元素 | 原始字节数据 |
| Uint32Array | 4 字节/元素 | 32位整数运算 |
| Sbox 表 | 256 字节 | 字节替换表 |
| 轮密钥数组 | 128 字节 | 32个轮密钥 |
| 中间变量 | ~144 字节 | 临时计算结果 |

#### 内存优化策略

1. **TypedArray 使用**: 优先使用 TypedArray 减少内存开销
2. **就地计算**: 尽可能重用数组避免额外分配
3. **批量处理**: 一次处理多个块提高缓存利用率

### 性能特征

#### 时间复杂度

- **密钥扩展**: O(1) - 固定 32 次迭代
- **单块加密**: O(1) - 固定 32 轮运算
- **整体加密**: O(n) - n 为块数量

#### 空间复杂度

- **内存使用**: O(n) - n 为输入数据大小
- **额外开销**: O(1) - 固定大小的中间变量

### 并发处理

模块当前不支持并发操作，建议：
1. 为每个并发任务创建独立的 TsSM4 实例
2. 避免在多线程环境中共享同一实例
3. 考虑使用 Web Workers 处理大量数据

## 故障排除指南

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

#### 密钥长度错误

**问题**: 密钥长度不是 16 字节
**解决**: 确保密钥为 16 字节长度
**位置**: [TsSM4.js:103-105](file://src/utils/TsSM4.js#L103-L105)

#### IV 参数错误

**问题**: CBC 模式下 IV 长度不正确
**解决**: 确保 IV 为 16 字节长度
**位置**: [TsSM4.js:119-121](file://src/utils/TsSM4.js#L119-L121)

#### 填充数据错误

**问题**: 去填充时数据格式不正确
**解决**: 确保使用相同的填充算法进行加解密
**位置**: [TsSM4.js:309-311](file://src/utils/TsSM4.js#L309-L311)

### 调试技巧

1. **启用详细日志**: 在开发环境中输出中间计算结果
2. **单元测试**: 为关键函数编写测试用例
3. **边界测试**: 测试空数据、单块数据、多块数据等场景

**章节来源**
- [TsSM4.js:103-121](file://src/utils/TsSM4.js#L103-L121)
- [TsSM4.js:309-311](file://src/utils/TsSM4.js#L309-L311)

## 结论

SM4 算法模块提供了完整、高效的中国国家标准加密实现。模块具有以下特点：

### 技术优势

1. **标准兼容**: 完全符合 SM4 算法规范
2. **性能优秀**: 使用 TypedArray 和优化算法
3. **接口友好**: 提供简洁的加密解密接口
4. **模式完整**: 支持 CBC 和 ECB 两种工作模式

### 应用场景

- 企业数据加密
- 网络通信安全
- 敏感信息保护
- 符合国家标准的系统集成

### 发展建议

1. **添加更多模式**: 考虑支持 OFB、CFB 等模式
2. **性能优化**: 实现 SIMD 指令集优化
3. **安全性增强**: 添加完整性校验机制
4. **文档完善**: 提供更详细的使用示例

该模块为企业级应用提供了可靠的加密解决方案，满足了中国国家标准的要求，同时保持了良好的性能和易用性。