6.8 KiB
6.8 KiB
| name | description |
|---|---|
| jjb-common-lib-crypto | 定义 @cqsjjb/jjb-common-lib crypto 模块使用规范。在使用 AES_128_Encrypt、AES_128_Decrypt、MD5 时查阅。 |
crypto 模块使用规范
概述
crypto 模块是 @cqsjjb/jjb-common-lib 通用工具库中的加解密模块，基于 cryptojs 实现，提供 AES-128 加解密和 MD5 哈希功能。
导入方式
import { crypto } from '@cqsjjb/jjb-common-lib';
内置方法详解
AES_128_Encrypt(content)
AES-128 位加密。
参数：
content(string): 待加密内容
返回值：
string: 加密后的字符串
示例：
import { crypto } from '@cqsjjb/jjb-common-lib';
// 加密字符串
const encrypted = crypto.AES_128_Encrypt('123');
console.log(encrypted); // 输出加密后的字符串
// 加密敏感信息
const password = crypto.AES_128_Encrypt('myPassword123');
使用场景：
- 加密敏感数据（如密码、身份证号等）
- 加密需要传输的敏感信息
- 数据存储前的加密处理
注意事项：
- 加密后的字符串长度会比原字符串长
- 相同的输入每次加密结果可能不同（如果使用了随机 IV）
- 加密后的数据需要使用对应的解密方法才能还原
AES_128_Decrypt(content)
AES-128 位解密。
参数：
content(string): 已加密内容
返回值：
string: 解密后的字符串
示例：
import { crypto } from '@cqsjjb/jjb-common-lib';
// 解密字符串
const encrypted = 'xxxxxx'; // 加密后的字符串
const decrypted = crypto.AES_128_Decrypt(encrypted);
console.log(decrypted); // 输出解密后的原始内容
// 解密密码
const encryptedPassword = '...'; // 从服务器获取的加密密码
const password = crypto.AES_128_Decrypt(encryptedPassword);
使用场景：
- 解密从服务器获取的加密数据
- 解密本地存储的加密信息
- 解密传输过程中加密的数据
注意事项：
- 只能解密使用
AES_128_Encrypt加密的数据 - 如果加密内容格式不正确，解密可能失败
- 确保加密和解密使用相同的密钥和算法配置
MD5(content)
MD5 哈希加密。
参数：
content(string): 待加密内容
返回值：
string: MD5 字符串（32 位十六进制字符串）
示例：
import { crypto } from '@cqsjjb/jjb-common-lib';
// MD5 加密
const hash = crypto.MD5('123');
console.log(hash); // => "202cb962ac59075b964b07152d234b70"
// 加密密码（用于密码校验）
const password = 'userPassword';
const passwordHash = crypto.MD5(password);
console.log(passwordHash);
// 生成文件哈希
const fileContent = 'file content here';
const fileHash = crypto.MD5(fileContent);
使用场景：
- 密码哈希存储（单向加密，不可逆）
- 数据完整性校验
- 生成唯一标识符
- 文件内容校验
注意事项：
- MD5 是单向哈希函数，无法解密还原原始内容
- 相同的输入总是产生相同的输出
- MD5 已不推荐用于密码存储（建议使用更安全的算法如 bcrypt），但仍可用于数据校验
使用示例
密码加密存储
import { crypto } from '@cqsjjb/jjb-common-lib';
// 用户注册时加密密码
function registerUser(username, password) {
// 使用 MD5 加密密码（注意：实际项目中应使用更安全的算法）
const passwordHash = crypto.MD5(password);
// 发送到服务器
return http.Post('/api/register', {
username,
password: passwordHash
});
}
敏感数据加密传输
import { crypto } from '@cqsjjb/jjb-common-lib';
// 加密敏感信息后传输
function submitSensitiveData(data) {
const encryptedData = crypto.AES_128_Encrypt(JSON.stringify(data));
return http.Post('/api/submit', {
encryptedData
});
}
数据解密处理
import { crypto } from '@cqsjjb/jjb-common-lib';
// 从服务器获取加密数据并解密
function getDecryptedData() {
return http.Get('/api/data')
.then(res => {
if (res.success) {
// 解密数据
const decrypted = crypto.AES_128_Decrypt(res.data.encryptedContent);
return JSON.parse(decrypted);
}
});
}
数据完整性校验
import { crypto } from '@cqsjjb/jjb-common-lib';
// 校验数据是否被篡改
function verifyData(data, expectedHash) {
const dataHash = crypto.MD5(JSON.stringify(data));
return dataHash === expectedHash;
}
// 使用示例
const data = { id: 1, name: 'test' };
const hash = crypto.MD5(JSON.stringify(data));
// 传输后校验
const isValid = verifyData(data, hash);
console.log('数据完整性:', isValid);
安全注意事项
AES 加密
- 密钥管理：确保加密密钥的安全存储，不要硬编码在代码中
- IV（初始化向量）：如果使用随机 IV，需要将 IV 与密文一起存储
- 算法选择：AES-128 适用于大多数场景，如需更高安全性可使用 AES-256
MD5 哈希
- 密码存储：不推荐使用 MD5 存储密码，建议使用 bcrypt、argon2 等专门用于密码的哈希算法
- 碰撞风险：MD5 存在碰撞风险，不适合用于安全关键场景
- 数据校验：MD5 仍可用于数据完整性校验和生成唯一标识符
最佳实践
- 敏感数据：使用 AES 加密存储和传输敏感数据
- 密码处理：使用专门的密码哈希算法（如 bcrypt），而不是 MD5
- 密钥管理：密钥应存储在安全的地方，不要暴露在前端代码中
- 错误处理：加密/解密失败时应妥善处理错误，不要暴露敏感信息
相关模块
- 详细文档：参考
reference/crypto.d.ts查看完整的类型定义和 API 文档 - 底层实现：基于 cryptojs 库实现
常见问题
加密后数据长度变化
AES 加密后的数据长度会变化，通常比原数据长。这是因为：
- 加密算法会对数据进行填充
- 可能包含 IV（初始化向量）
- Base64 编码会增加长度
加密结果不一致
如果相同的输入产生不同的加密结果，这是正常的，因为：
- 使用了随机 IV（初始化向量）
- 这是加密算法的安全特性
MD5 不可逆
MD5 是单向哈希函数，无法从哈希值还原原始内容。如果需要可逆加密，应使用 AES 加密。
注意事项
-
安全性：前端加密不能完全保证数据安全，敏感操作应在后端进行
-
性能：加密/解密操作有一定性能开销，避免在高频操作中使用
-
兼容性：确保在支持的浏览器环境中使用，现代浏览器都支持
-
错误处理：加密/解密可能失败，应添加适当的错误处理
-
密钥管理：不要在前端代码中硬编码密钥，密钥应由后端管理或通过安全方式传递