12 KiB
12 KiB
加密解密 API
**本文档引用的文件** - [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)目录
简介
本项目是一个基于 SM4 对称加密算法的 JavaScript 加密解密工具包。该工具包提供了完整的加密解密功能，支持 ECB 和 CBC 两种加密模式，内置 Base64 编解码处理，并集成了 HTTP 请求加密传输功能。系统采用模块化设计，通过 TsCrypto 类封装 SM4 加密算法，通过 TsSM4 类实现具体的 SM4 算法逻辑，通过 TsHttpUtil 类实现 HTTP 请求的自动加密功能。
项目结构
该项目采用模块化组织结构，主要包含以下核心模块：
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 加密器
TsCrypto 是整个加密系统的核心封装类，负责提供简化的加密解密接口。它内部使用 TsSM4 类来执行实际的加密解密操作。
主要特性：
- 基于 SM4 算法的对称加密
- 内置 Base64 编解码处理
- 支持 ECB 和 CBC 模式配置
- 自动密钥管理
章节来源
TsSM4 SM4 算法实现
TsSM4 类实现了完整的 SM4 对称加密算法，包括密钥扩展、加密轮函数、填充和去填充等功能。
核心功能：
- 完整的 SM4 算法实现
- 支持 ECB 和 CBC 两种模式
- 自动填充和去填充机制
- Base64 和文本两种输出格式
章节来源
TsGlobalConfig 全局配置
提供全局配置管理功能，支持动态设置和获取加密密钥、HTTP 前缀等配置项。
配置选项：
- base64Key: Base64 编码的密钥字符串
- prefix: HTTP 请求前缀
- onHttpError: HTTP 错误回调函数
- httpParams: HTTP 参数处理函数
章节来源
架构概览
系统采用分层架构设计，从上到下分为应用层、工具层、算法层和依赖层：
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
图表来源
详细组件分析
TsCrypto 类详细分析
TsCrypto 类提供了简洁的加密解密接口，内部封装了复杂的加密细节。
类结构图
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 : "使用"
图表来源
加密流程序列图
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 : 返回密文
图表来源
章节来源
TsSM4 类详细分析
TsSM4 类实现了完整的 SM4 算法，包括密钥扩展、加密轮函数和填充机制。
算法流程图
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([结束])
图表来源
关键算法实现
密钥扩展算法：
- 使用 FK 常量和 CK 数组
- 生成 32 轮加密密钥
- 每轮密钥长度 32 位
加密轮函数：
- 实现 τ 变换和线性变换
- 包含 S 盒替换
- 支持 32 轮加密
填充机制：
- 使用 PKCS7 填充标准
- 自动处理任意长度数据
- 支持去填充操作
章节来源
HTTP 加密传输集成
TsHttpUtil 类集成了加密功能，实现了 HTTP 请求的自动加密传输。
加密传输流程
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 : 返回解析后的数据
图表来源
章节来源
依赖关系分析
外部依赖
项目的主要外部依赖包括：
| 依赖包 | 版本 | 用途 |
|---|---|---|
| base64-js | 1.5.1 | Base64 编解码处理 |
| umi-request | 1.4.0 | HTTP 请求库 |
内部模块依赖
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
图表来源
章节来源
性能考虑
加密性能优化
-
内存管理：
- 使用 TypedArray 进行高效的数据处理
- 避免不必要的数据拷贝
- 合理使用缓冲区复用
-
算法优化：
- 采用 32 位整数运算提高性能
- 使用预计算的 S 盒表
- 优化循环结构减少开销
-
I/O 优化：
- Base64 编解码使用高效的库实现
- 批量处理数据块避免频繁调用
安全性最佳实践
-
密钥管理：
- 密钥必须为 16 字节长度
- 建议使用安全的随机数生成器
- 定期更换密钥
-
模式选择：
- CBC 模式提供更好的安全性
- ECB 模式仅适用于相同明文的场景
- IV 必须随机且唯一
-
填充安全：
- 使用标准的 PKCS7 填充
- 验证去填充结果的有效性
故障排除指南
常见错误及解决方案
密钥长度错误
- 错误信息：
key should be a 16 bytes string - 解决方案：确保密钥为 16 字节长度的 Base64 编码
IV 初始化错误
- 错误信息：
iv error - 解决方案：在 CBC 模式下提供 16 字节长度的 IV
数据解密失败
- 可能原因：密钥不匹配、数据损坏
- 解决方案：验证密钥正确性，检查数据完整性
Base64 编码问题
- 可能原因：输入数据格式不正确
- 解决方案：确保输入为有效的字符串或 Buffer
调试技巧
-
启用开发模式：
// 在开发环境中启用详细日志 const isDev = TsCommon.isDevelopment(); -
验证加密结果：
const original = "测试数据"; const encrypted = TsCrypto.encrypt(original); const decrypted = TsCrypto.decrypt(encrypted); console.assert(original === decrypted, "加密解密结果不匹配");
章节来源
结论
本加密解密模块提供了完整的 SM4 对称加密解决方案，具有以下特点：
- 功能完整：支持 ECB 和 CBC 两种加密模式，提供 Base64 编解码
- 易于使用：提供简洁的 API 接口，便于集成到现有项目中
- 安全可靠：采用标准的 SM4 算法和 PKCS7 填充机制
- 性能优化：使用高效的 TypedArray 和优化的算法实现
该模块特别适合需要数据加密传输和存储的应用场景，如 API 数据传输、用户敏感信息存储等。通过合理的配置和使用，可以有效提升应用程序的安全性。