484 lines
13 KiB
Markdown
484 lines
13 KiB
Markdown
# laoqianjunzi-crypto
|
|
|
|
`laoqianjunzi-crypto` 是一个面向 `uni-app x` 的多端加密工具插件，统一封装了文本编解码、摘要、HMAC、AES、DES、3DES、RC4、RSA 等常见能力。
|
|
|
|
插件当前覆盖以下平台：
|
|
|
|
- `App-Android`
|
|
- `App-iOS`
|
|
- `App-Harmony`
|
|
- `Web`
|
|
- `微信小程序`
|
|
|
|
适合以下场景：
|
|
|
|
- 业务请求签名、摘要校验、口令派生前的基础处理
|
|
- 本地敏感文本或字节数据加解密
|
|
- 公私钥生成、RSA 短文本加解密
|
|
- 需要在多端复用同一套加密接口的 `uni-app x` 项目
|
|
|
|
## 功能概览
|
|
|
|
- 支持 `utf8`、`hex`、`base64`、`base64url`、`latin1`、`utf16` 编解码
|
|
- 支持 `md5`、`sha1`、`sha256`、`sha512` 摘要
|
|
- 支持 `HMAC-SHA1`、`HMAC-SHA256`、`HMAC-SHA512`
|
|
- 支持 AES 文本加解密与 AES 字节数组加解密
|
|
- 支持 DES、3DES、RC4 文本加解密
|
|
- 支持 RSA 密钥对生成与短文本加解密
|
|
- 支持读取当前运行时的底层引擎信息
|
|
- 所有计算均在本地执行，不包含网络上传逻辑
|
|
|
|
## 版本要求
|
|
|
|
根据插件当前 `package.json` 配置，建议使用以下环境：
|
|
|
|
- `HBuilderX` `5.07` 或更高版本
|
|
- `uni-app x` `4.75` 或更高版本
|
|
|
|
## 平台支持矩阵
|
|
|
|
| 平台 | 加密能力 | RSA | 运行时引擎 |
|
|
| --- | --- | --- | --- |
|
|
| App-Android | 支持 | 支持 | `JCA` 原生桥接 |
|
|
| App-iOS | 支持 | 支持 | `CommonCrypto` 原生桥接 |
|
|
| App-Harmony | 支持 | 支持 | `@ohos/crypto-js` + 原生 RSA |
|
|
| Web | 支持 | 支持 | `crypto-es` + `jsencrypt` |
|
|
| 微信小程序 | 支持 | 支持 | `crypto-es` + `jsencrypt` |
|
|
|
|
说明：
|
|
|
|
- `describeCryptoRuntime()` 可返回当前平台名、底层引擎名、是否支持高级分组模式、是否经过原生桥接
|
|
- Web 与微信小程序端的实现基于纯脚本运行时，App 端优先走原生桥接
|
|
- 文本加密、文本解密、摘要、签名、RSA 等接口均采用统一函数签名，便于业务跨端复用
|
|
|
|
## 安装与导入
|
|
|
|
将插件放入项目 `uni_modules` 目录后，直接从插件根目录导入：
|
|
|
|
```uts
|
|
import {
|
|
aesDecryptBytes,
|
|
aesDecryptText,
|
|
aesEncryptBytes,
|
|
aesEncryptText,
|
|
createRsaPair,
|
|
decodeText,
|
|
defaultByteCipherOptions,
|
|
defaultTextCipherOptions,
|
|
describeCryptoRuntime,
|
|
digestText,
|
|
encodeText,
|
|
rsaDecryptText,
|
|
rsaEncryptText,
|
|
signText
|
|
} from "@/uni_modules/laoqianjunzi-crypto"
|
|
|
|
import type {
|
|
CryptoByteCipherOptions,
|
|
CryptoRsaPair,
|
|
CryptoRuntimeSnapshot,
|
|
CryptoTextCipherOptions
|
|
} from "@/uni_modules/laoqianjunzi-crypto"
|
|
```
|
|
|
|
请注意：
|
|
|
|
- 只从插件根目录导入，不要直接导入插件内部 `utssdk` 文件
|
|
- 业务代码建议统一使用插件根导出，便于后续维护和跨端类型识别
|
|
|
|
## 快速开始
|
|
|
|
下面示例演示最常用的四类能力：运行时信息、文本编解码、摘要/HMAC、AES 文本加解密、RSA 密钥对与短文本加解密。
|
|
|
|
```uts
|
|
import {
|
|
aesDecryptText,
|
|
aesEncryptText,
|
|
createRsaPair,
|
|
decodeText,
|
|
defaultTextCipherOptions,
|
|
describeCryptoRuntime,
|
|
digestText,
|
|
encodeText,
|
|
rsaDecryptText,
|
|
rsaEncryptText,
|
|
signText
|
|
} from "@/uni_modules/laoqianjunzi-crypto"
|
|
|
|
import type {
|
|
CryptoRsaPair,
|
|
CryptoRuntimeSnapshot,
|
|
CryptoTextCipherOptions
|
|
} from "@/uni_modules/laoqianjunzi-crypto"
|
|
|
|
function runCryptoDemo(): void {
|
|
const runtime: CryptoRuntimeSnapshot = describeCryptoRuntime()
|
|
console.log("runtime", runtime.platformName, runtime.engineName)
|
|
|
|
const plainText = "Hello uni-app x"
|
|
const secretText = "1234567890abcdef"
|
|
const ivText = "fedcba0987654321"
|
|
|
|
const base64Text = encodeText("base64", plainText)
|
|
const restoreText = decodeText("base64", base64Text)
|
|
console.log("base64", base64Text)
|
|
console.log("restore", restoreText)
|
|
|
|
const sha256Text = digestText("sha256", plainText)
|
|
const hmacText = signText("sha256", "sign-key", plainText)
|
|
console.log("sha256", sha256Text)
|
|
console.log("hmac", hmacText)
|
|
|
|
const aesOptions: CryptoTextCipherOptions = defaultTextCipherOptions()
|
|
aesOptions.mode = "CBC"
|
|
aesOptions.padding = "PKCS7"
|
|
aesOptions.ivText = ivText
|
|
aesOptions.keyLength = 16
|
|
|
|
const aesCipherText = aesEncryptText(secretText, plainText, aesOptions)
|
|
const aesPlainText = aesDecryptText(secretText, aesCipherText, aesOptions)
|
|
console.log("aes cipher", aesCipherText)
|
|
console.log("aes plain", aesPlainText)
|
|
|
|
const rsaPair: CryptoRsaPair = createRsaPair(2048)
|
|
const rsaCipherText = rsaEncryptText(rsaPair.publicKey, plainText, "base64")
|
|
const rsaPlainText = rsaDecryptText(rsaPair.privateKey, rsaCipherText, "base64")
|
|
console.log("rsa plain", rsaPlainText)
|
|
}
|
|
```
|
|
|
|
## AES 字节数组示例
|
|
|
|
如果你的业务处理的是二进制数据，而不是普通字符串，建议使用字节接口：
|
|
|
|
```uts
|
|
import {
|
|
aesDecryptBytes,
|
|
aesEncryptBytes,
|
|
defaultByteCipherOptions
|
|
} from "@/uni_modules/laoqianjunzi-crypto"
|
|
|
|
import type { CryptoByteCipherOptions } from "@/uni_modules/laoqianjunzi-crypto"
|
|
|
|
function textToBytes(input: string): Uint8Array {
|
|
const output = new Uint8Array(input.length)
|
|
let index = 0
|
|
while (index < input.length) {
|
|
const code = input.charCodeAt(index)
|
|
output[index] = code == null ? 0 : code & 0xff
|
|
index += 1
|
|
}
|
|
return output
|
|
}
|
|
|
|
function bytesToText(input: Uint8Array): string {
|
|
let output = ""
|
|
let index = 0
|
|
while (index < input.length) {
|
|
output += String.fromCharCode(input[index])
|
|
index += 1
|
|
}
|
|
return output
|
|
}
|
|
|
|
function runByteCipherDemo(): void {
|
|
const options: CryptoByteCipherOptions = defaultByteCipherOptions()
|
|
options.mode = "CTR"
|
|
options.padding = "PKCS7"
|
|
options.keyLength = 16
|
|
|
|
const secretBytes = textToBytes("1234567890abcdef")
|
|
const plainBytes = textToBytes("hello-bytes")
|
|
|
|
const cipherBytes = aesEncryptBytes(secretBytes, plainBytes, options)
|
|
const restoreBytes = aesDecryptBytes(secretBytes, cipherBytes, options)
|
|
console.log("byte plain", bytesToText(restoreBytes))
|
|
console.log("cipher length", cipherBytes.length)
|
|
}
|
|
```
|
|
|
|
## 对外类型
|
|
|
|
### CryptoDigestKind
|
|
|
|
摘要算法枚举：
|
|
|
|
- `md5`
|
|
- `sha1`
|
|
- `sha256`
|
|
- `sha512`
|
|
|
|
### CryptoMacKind
|
|
|
|
HMAC 算法枚举：
|
|
|
|
- `sha1`
|
|
- `sha256`
|
|
- `sha512`
|
|
|
|
### CryptoCodecKind
|
|
|
|
文本编解码枚举：
|
|
|
|
- `utf8`
|
|
- `hex`
|
|
- `base64`
|
|
- `base64url`
|
|
- `latin1`
|
|
- `utf16`
|
|
|
|
### CryptoBlockMode
|
|
|
|
分组模式枚举：
|
|
|
|
- `ECB`
|
|
- `CBC`
|
|
- `CFB`
|
|
- `CTR`
|
|
- `CTRGladman`
|
|
- `OFB`
|
|
|
|
### CryptoPaddingKind
|
|
|
|
填充模式枚举：
|
|
|
|
- `PKCS7`
|
|
- `ANSI_X923`
|
|
- `ISO_10126`
|
|
- `ISO_97971`
|
|
- `NONE`
|
|
- `ZERO`
|
|
|
|
### RsaOutputKind
|
|
|
|
RSA 密文输出格式：
|
|
|
|
- `base64`
|
|
- `hex`
|
|
|
|
### CryptoTextCipherOptions
|
|
|
|
AES 文本加解密参数：
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
| --- | --- | --- | --- |
|
|
| `mode` | `CryptoBlockMode` | 是 | 分组模式 |
|
|
| `padding` | `CryptoPaddingKind` | 是 | 填充模式 |
|
|
| `ivText` | `string \\| null` | 是 | 初始向量文本，`ECB` 模式可传 `null` |
|
|
| `keyLength` | `number \\| null` | 是 | AES 密钥长度，建议传 `16`、`24`、`32` |
|
|
|
|
### CryptoByteCipherOptions
|
|
|
|
AES 字节加解密参数：
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
| --- | --- | --- | --- |
|
|
| `mode` | `CryptoBlockMode` | 是 | 分组模式 |
|
|
| `padding` | `CryptoPaddingKind` | 是 | 填充模式 |
|
|
| `ivBytes` | `Uint8Array \\| null` | 是 | 初始向量字节数组，`ECB` 模式可传 `null` |
|
|
| `keyLength` | `number \\| null` | 是 | AES 密钥长度，建议传 `16`、`24`、`32` |
|
|
|
|
### CryptoTripleDesOptions
|
|
|
|
3DES 参数：
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
| --- | --- | --- | --- |
|
|
| `mode` | `"ECB" \\| "CBC"` | 是 | 3DES 当前支持的分组模式 |
|
|
| `ivText` | `string \\| null` | 是 | 初始向量文本，`ECB` 模式可传 `null` |
|
|
|
|
### CryptoDesOptions
|
|
|
|
DES 参数：
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
| --- | --- | --- | --- |
|
|
| `mode` | `CryptoBlockMode` | 是 | 分组模式 |
|
|
| `padding` | `CryptoPaddingKind` | 是 | 填充模式 |
|
|
| `ivText` | `string \\| null` | 是 | 初始向量文本，`ECB` 模式可传 `null` |
|
|
|
|
### CryptoRsaPair
|
|
|
|
RSA 密钥对对象：
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
| --- | --- | --- | --- |
|
|
| `publicKey` | `string` | 是 | 公钥 PEM 文本 |
|
|
| `privateKey` | `string` | 是 | 私钥 PEM 文本 |
|
|
|
|
### CryptoRuntimeSnapshot
|
|
|
|
运行时描述对象：
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
| --- | --- | --- | --- |
|
|
| `platformName` | `string` | 是 | 平台名称 |
|
|
| `engineName` | `string` | 是 | 当前底层实现名称 |
|
|
| `supportsAdvancedModes` | `boolean` | 是 | 是否支持高级分组模式 |
|
|
| `usesNativeBridge` | `boolean` | 是 | 是否经过原生桥接 |
|
|
|
|
## 默认参数函数
|
|
|
|
### defaultTextCipherOptions()
|
|
|
|
返回 AES 文本加解密默认参数：
|
|
|
|
| 字段 | 默认值 |
|
|
| --- | --- |
|
|
| `mode` | `CBC` |
|
|
| `padding` | `PKCS7` |
|
|
| `ivText` | `0123456789abcdef` |
|
|
| `keyLength` | `16` |
|
|
|
|
### defaultByteCipherOptions()
|
|
|
|
返回 AES 字节加解密默认参数：
|
|
|
|
| 字段 | 默认值 |
|
|
| --- | --- |
|
|
| `mode` | `CBC` |
|
|
| `padding` | `PKCS7` |
|
|
| `ivBytes` | `0123456789abcdef` 的 ASCII 字节 |
|
|
| `keyLength` | `16` |
|
|
|
|
### defaultTripleDesOptions()
|
|
|
|
返回 3DES 默认参数：
|
|
|
|
| 字段 | 默认值 |
|
|
| --- | --- |
|
|
| `mode` | `CBC` |
|
|
| `ivText` | `12345678` |
|
|
|
|
### defaultDesOptions()
|
|
|
|
返回 DES 默认参数：
|
|
|
|
| 字段 | 默认值 |
|
|
| --- | --- |
|
|
| `mode` | `CBC` |
|
|
| `padding` | `PKCS7` |
|
|
| `ivText` | `12345678` |
|
|
|
|
## 运行时信息函数
|
|
|
|
### describeCryptoRuntime()
|
|
|
|
返回当前平台的运行时信息：
|
|
|
|
```uts
|
|
const runtime = describeCryptoRuntime()
|
|
console.log(runtime.platformName)
|
|
console.log(runtime.engineName)
|
|
console.log(runtime.supportsAdvancedModes)
|
|
console.log(runtime.usesNativeBridge)
|
|
```
|
|
|
|
## API 清单
|
|
|
|
### 编解码
|
|
|
|
| 函数 | 说明 | 返回值 |
|
|
| --- | --- | --- |
|
|
| `encodeText(codec, plainText)` | 将普通文本编码为指定格式文本 | `string` |
|
|
| `decodeText(codec, encodedText)` | 将指定格式文本还原为普通文本 | `string` |
|
|
|
|
### 摘要与签名
|
|
|
|
| 函数 | 说明 | 返回值 |
|
|
| --- | --- | --- |
|
|
| `digestText(kind, plainText)` | 计算摘要，结果为十六进制字符串 | `string` |
|
|
| `signText(kind, secretText, plainText)` | 计算 HMAC，结果为十六进制字符串 | `string` |
|
|
|
|
### AES 文本加解密
|
|
|
|
| 函数 | 说明 | 返回值 |
|
|
| --- | --- | --- |
|
|
| `aesEncryptText(secretText, plainText, options)` | 使用文本密钥加密文本 | `string` |
|
|
| `aesDecryptText(secretText, cipherText, options)` | 使用文本密钥解密文本 | `string` |
|
|
|
|
### AES 字节加解密
|
|
|
|
| 函数 | 说明 | 返回值 |
|
|
| --- | --- | --- |
|
|
| `aesEncryptBytes(secretBytes, plainBytes, options)` | 使用字节密钥加密字节数组 | `Uint8Array` |
|
|
| `aesDecryptBytes(secretBytes, cipherBytes, options)` | 使用字节密钥解密字节数组 | `Uint8Array` |
|
|
|
|
### 3DES
|
|
|
|
| 函数 | 说明 | 返回值 |
|
|
| --- | --- | --- |
|
|
| `tripleDesEncryptText(secretText, plainText, options)` | 3DES 文本加密 | `string` |
|
|
| `tripleDesDecryptText(secretText, cipherText, options)` | 3DES 文本解密 | `string` |
|
|
|
|
### DES
|
|
|
|
| 函数 | 说明 | 返回值 |
|
|
| --- | --- | --- |
|
|
| `desEncryptText(secretText, plainText, options)` | DES 文本加密 | `string` |
|
|
| `desDecryptText(secretText, cipherText, options)` | DES 文本解密 | `string` |
|
|
|
|
### RC4
|
|
|
|
| 函数 | 说明 | 返回值 |
|
|
| --- | --- | --- |
|
|
| `rc4EncryptText(secretText, plainText)` | RC4 加密，返回十六进制密文 | `string` |
|
|
| `rc4DecryptText(secretText, cipherHexText)` | RC4 解密十六进制密文 | `string` |
|
|
|
|
### RSA
|
|
|
|
| 函数 | 说明 | 返回值 |
|
|
| --- | --- | --- |
|
|
| `createRsaPair(keySize)` | 生成 RSA 密钥对 | `CryptoRsaPair` |
|
|
| `rsaEncryptText(publicKey, plainText, outputKind)` | 使用公钥加密短文本 | `string` |
|
|
| `rsaDecryptText(privateKey, cipherText, outputKind)` | 使用私钥解密短文本 | `string` |
|
|
|
|
建议：
|
|
|
|
- `keySize` 推荐使用 `1024`、`2048`、`3072`、`4096`
|
|
- 一般业务默认建议使用 `2048`
|
|
|
|
## 使用建议
|
|
|
|
- 编解码、摘要、HMAC 建议直接使用字符串接口，返回值稳定、便于日志记录和接口传输
|
|
- 处理图片片段、协议报文、蓝牙包、文件块等二进制内容时，优先使用 `aesEncryptBytes` 与 `aesDecryptBytes`
|
|
- AES 跨端调用时，`keyLength` 建议固定传 `16`、`24`、`32` 之一，避免不同运行时对推断长度的理解差异
|
|
- 使用 `CBC`、`CFB`、`CTR`、`OFB` 等模式时，建议显式传入业务自定义 `ivText` 或 `ivBytes`
|
|
- `RSA` 更适合短文本、密钥交换或签名相关前置处理，不适合大体积正文直接加解密
|
|
- `RC4`、`DES`、`3DES` 更适用于兼容特定协议场景，新业务优先建议选择 `AES` 或 `RSA`
|
|
|
|
## 异常处理建议
|
|
|
|
参数不合法、密文格式不正确、密钥与向量不匹配时，接口可能抛出错误。业务代码建议统一使用 `try/catch` 包裹：
|
|
|
|
```uts
|
|
import {
|
|
aesEncryptText,
|
|
defaultTextCipherOptions
|
|
} from "@/uni_modules/laoqianjunzi-crypto"
|
|
|
|
try {
|
|
const options = defaultTextCipherOptions()
|
|
const cipherText = aesEncryptText("1234567890abcdef", "hello", options)
|
|
console.log(cipherText)
|
|
} catch (error) {
|
|
console.error("crypto error", error)
|
|
}
|
|
```
|
|
|
|
## 注意事项
|
|
|
|
- 本插件面向 `uni-app x`，不面向传统 `uni-app` 页面运行时
|
|
- 文本接口默认适合 UTF-8 文本场景；如果你的原始数据本身不是普通文本，请优先使用字节接口
|
|
- `ECB` 模式不依赖 IV，其余分组模式建议始终显式设置 IV
|
|
- RSA 密文输出格式由 `outputKind` 控制，发送方与接收方应保持一致
|
|
- 通过 `default*Options()` 获取参数对象后，可按当前业务需求覆盖默认值
|
|
|
|
## 示例页面
|
|
|
|
插件内已提供示例页面，可用于快速验证能力是否正常：
|
|
|
|
- `uni_modules/laoqianjunzi-crypto/pages/index`
|
|
|
|
如果项目已在 `pages.json` 中注册该页面，可直接运行到对应页面进行体验。
|