更新记录

1.0.0（2026-04-20）

• 首次发布
• RSA 非对称加密：密钥生成、公钥加密、私钥解密、签名、验签、分段加解密（超长数据）
• DSA 数字签名：密钥生成、签名、验签
• 对称加密：支持 AES、ARCFOUR、Blowfish、DES、DESede、RC2 算法
• PBE 密码加密：支持 PBEWithMD5AndDES、PBEWithSHA1AndDESede
• 摘要算法：支持 MD5、SHA-1、SHA-256、SHA-384、SHA-512，输出格式支持 hex 和 base64
• HMAC 消息认证：支持 HmacMD5、HmacSHA1、HmacSHA256、HmacSHA384、HmacSHA512
• 所有接口均提供异步（Promise）和同步（Sync）两种调用方式
• 密钥格式：支持 PKCS#8 Base64 和 PEM 两种格式
• 加密模式：对称加密支持 ECB/CBC 模式和 PKCS5Padding/NoPadding 填充
• 国际化：内置中文/英文语言包，支持 t()/tf() 翻译函数和 getLocale()/setLocale() 语言切换
• 耗时统计：提供 startTime()/getElapsed()/getElapsedMs() 工具函数

平台兼容性

uni-app(4.0)

uni-app x(4.0)

dida2-crypto 加密算法库

基于 UTS 的跨平台加密算法插件，提供 RSA、DSA、AES、PBE、摘要、HMAC 等常用密码学算法，所有接口均提供异步（Promise）和同步（Sync 后缀）两种调用方式。

支持平台：Android、HarmonyOS

iOS 暂不支持。作者因 Apple 开发者账号过期，近期无更新计划。如有人能提供 Apple 开发者账号用于测试，可联系作者推进 iOS 版本支持。如需支持新的算法，也欢迎向作者反馈。

平台兼容性

• 最低 Android 版本：API 21（Android 5.0）
• HarmonyOS 版本：API 14+
• HBuilderX：3.6.8+（Android），4.22+（HarmonyOS）
• uni-app / uni-app x：4.0+

各平台算法支持总览

以下是各模块在不同平台的支持情况。标注 ✗ 的功能在对应平台调用时会直接抛出错误，请在开发前确认目标平台支持情况。

RSA 非对称加密

DSA 数字签名

对称加密

PBE 密码加密

摘要算法

HMAC 消息认证码

通用功能

⚠️ 鸿蒙平台重要提醒

如果你需要在鸿蒙平台使用本插件，请务必注意以下限制：

1. 同步 API 不可用：所有带 Sync 后缀的同步 API（如 generateKeyPairSync、encryptSync、digestSync 等）在鸿蒙平台会抛出错误，请统一使用异步 API。这是因为鸿蒙 cryptoFramework 仅为异步接口。
2. DSA 不支持：DSA 密钥生成、签名、验签在鸿蒙平台调用会抛出 DSAError(91104)。
3. PBE 不支持：PBE 加密/解密在鸿蒙平台调用会抛出 SymmetricError(91306)。
4. 对称加密仅支持 AES：Blowfish、DES、DESede、RC2、ARCFOUR 在鸿蒙平台调用会抛出 SymmetricError(91304)。
5. PKCS5Padding 映射为 PKCS7：鸿蒙平台的 PKCS5Padding 内部自动映射为 PKCS7，两者实现完全相同，无需额外处理。
6. NoPadding 自动补零：AES NoPadding 模式下，输入数据会自动补零至 16 字节对齐，解密时自动去除尾部补零。如原始数据本身以 \0 结尾，可能会丢失尾部零字节，建议使用 PKCS5Padding 填充模式。
7. 平台判断：使用 isHarmonyOS 常量可在运行时判断当前平台，建议在跨平台代码中使用此常量做条件分支。

快速开始

安装

在 HBuilderX 中通过插件市场导入 dida2-crypto 插件即可。

导入

// 按需导入所需功能
import {
  // RSA
  generateKeyPair, encrypt, decrypt, sign, verify,
  // DSA
  dsaGenerateKeyPair, dsaSign, dsaVerify,
  // 对称加密
  symmetricGenerateKey, symmetricEncrypt, symmetricDecrypt,
  // PBE
  pbeEncrypt, pbeDecrypt,
  // 摘要
  digest,
  // HMAC
  hmac,
  // 平台检测
  isHarmonyOS,
  // 耗时统计
  startTime, getElapsed, getElapsedMs
} from '@/uni_modules/dida2-crypto'

// 导入类型
import type {
  RSAKeyPair, RSAKeyFormat, RSAOptions, RSASignAlgorithm,
  DSAKeyPair, DSAKeyFormat, DSAOptions, DSASignAlgorithm,
  SymmetricAlgorithm, SymmetricMode, SymmetricPadding, SymmetricOptions,
  PBEAlgorithm, PBEOptions, PBEEncryptResult,
  DigestAlgorithm, DigestOutputFormat,
  HmacAlgorithm
} from '@/uni_modules/dida2-crypto'

API 文档

所有接口均提供异步（Promise）和同步（Sync 后缀）两种调用方式。

鸿蒙平台：同步 API 会抛出错误，请使用异步 API。详见上方「鸿蒙平台重要提醒」。

RSA

generateKeyPair(keySize?, options?)

生成 RSA 密钥对。

返回值：Promise<RSAKeyPair> / RSAKeyPair

// 异步
const keyPair = await generateKeyPair(2048, { keyFormat: 'pem' })
console.log(keyPair.publicKey)   // PEM 格式公钥
console.log(keyPair.privateKey)  // PEM 格式私钥

// 同步（仅 Android）
const keyPair2 = generateKeyPairSync(2048, { keyFormat: 'pkcs8' })

encrypt(plainText, publicKey, options?)

使用公钥加密。

可选加密算法：

• RSA/ECB/PKCS1Padding（默认）
• RSA/ECB/OAEPWithSHA-1AndMGF1Padding
• RSA/ECB/OAEPWithSHA-256AndMGF1Padding

返回值：Promise<string> — Base64 编码的密文

const encrypted = await encrypt('Hello World', keyPair.publicKey)

decrypt(encryptedBase64, privateKey, options?)

使用私钥解密。

返回值：Promise<string> — 原文

const decrypted = await decrypt(encrypted, keyPair.privateKey)

sign(plainText, privateKey, options?)

使用私钥签名。

可选签名算法：SHA1withRSA、SHA256withRSA、SHA384withRSA、SHA512withRSA

返回值：Promise<string> — Base64 编码的签名

const signature = await sign('Hello World', keyPair.privateKey, {
  signAlgorithm: 'SHA256withRSA'
})

verify(plainText, signatureBase64, publicKey, options?)

使用公钥验签。

返回值：Promise<boolean> — 验签是否通过

const isValid = await verify('Hello World', signature, keyPair.publicKey, {
  signAlgorithm: 'SHA256withRSA'
})

DSA

⚠️ DSA 仅支持 Android 平台，鸿蒙平台调用会抛出 DSAError(91104)。DSA 仅用于签名/验签，不支持加密/解密。

dsaGenerateKeyPair(keySize?, options?)

生成 DSA 密钥对。

返回值：Promise<DSAKeyPair> / DSAKeyPair

const keyPair = await dsaGenerateKeyPair(2048, { keyFormat: 'pem' })

dsaSign(plainText, privateKey, options?)

DSA 私钥签名。

可选签名算法：SHA1withDSA、SHA256withDSA

返回值：Promise<string> — Base64 编码的签名

const signature = await dsaSign('Hello World', keyPair.privateKey, {
  signAlgorithm: 'SHA256withDSA'
})

dsaVerify(plainText, signatureBase64, publicKey, options?)

DSA 公钥验签。

返回值：Promise<boolean> — 验签是否通过

const isValid = await dsaVerify('Hello World', signature, keyPair.publicKey)

对称加密

⚠️ 鸿蒙平台仅支持 AES 算法，其他对称加密算法（ARCFOUR/Blowfish/DES/DESede/RC2）调用会抛出 SymmetricError(91304)。

symmetricGenerateKey(algorithm, keySize?)

生成对称加密密钥。

支持算法：AES、ARCFOUR、Blowfish、DES、DESede、RC2

密钥长度参考：

返回值：Promise<string> — Base64 编码的密钥

const keyBase64 = await symmetricGenerateKey('AES', 256)

symmetricEncrypt(plainText, keyBase64, algorithm, options?)

对称加密。

返回值：Promise<string> — Base64 编码的密文

// ECB 模式
const encrypted = await symmetricEncrypt('Hello', keyBase64, 'AES')

// CBC 模式
const encrypted2 = await symmetricEncrypt('Hello', keyBase64, 'AES', {
  mode: 'CBC',
  padding: 'PKCS5Padding',
  iv: ivBase64
})

symmetricDecrypt(cipherTextBase64, keyBase64, algorithm, options?)

对称解密，参数需与加密时一致。

返回值：Promise<string> — 原文

PBE 密码加密

⚠️ PBE 仅支持 Android 平台，鸿蒙平台调用会抛出 SymmetricError(91306)。

pbeEncrypt(plainText, password, algorithm, options?)

基于密码的加密。

支持算法：PBEWithMD5AndDES、PBEWithSHA1AndDESede

返回值：Promise<PBEEncryptResult>

const result = await pbeEncrypt('Hello World', 'myPassword', 'PBEWithMD5AndDES', {
  iterationCount: 1000
})
console.log(result.encrypted)      // Base64 密文
console.log(result.salt)           // Base64 盐值（解密时需要）
console.log(result.iterationCount) // 迭代次数

pbeDecrypt(cipherTextBase64, password, algorithm, options?)

PBE 解密。options.salt 为必填。

const decrypted = await pbeDecrypt(result.encrypted, 'myPassword', 'PBEWithMD5AndDES', {
  salt: result.salt,
  iterationCount: result.iterationCount
})

摘要算法

digest(plainText, algorithm, outputFormat?)

计算消息摘要。

支持算法：MD5、SHA-1、SHA-256、SHA-384、SHA-512

返回值：Promise<string> — 摘要值

const hash = await digest('Hello World', 'SHA-256')
// 默认输出 hex 格式: "a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b27718d2f5f5a0"

const hashBase64 = await digest('Hello World', 'SHA-256', 'base64')
// Base64 格式输出

HMAC 消息认证码

hmac(plainText, key, algorithm, outputFormat?)

计算 HMAC 值。

支持算法：HmacMD5、HmacSHA1、HmacSHA256、HmacSHA384、HmacSHA512

返回值：Promise<string> — HMAC 值

const hmacValue = await hmac('Hello World', 'mySecretKey', 'HmacSHA256')

耗时统计

startTime()

获取当前时间戳（毫秒），用于标记起始时间。

getElapsed(startMs)

计算耗时，返回耗时毫秒数字符串（不含单位）。

getElapsedMs(startMs)

计算耗时，返回耗时毫秒数（number 类型）。

import { startTime, getElapsed, getElapsedMs } from '@/uni_modules/dida2-crypto'

const t0 = startTime()
const result = await digest('Hello World', 'SHA-256')
const elapsed = '耗时: ' + getElapsed(t0) + ' ms'

// 或直接获取数值
const ms = getElapsedMs(t0)  // 15

平台检测

isHarmonyOS

boolean 常量，判断当前是否运行在鸿蒙平台。

• Android 平台：false
• 鸿蒙平台：true

import { isHarmonyOS } from '@/uni_modules/dida2-crypto'

if (isHarmonyOS) {
  // 鸿蒙平台特定逻辑
} else {
  // Android 平台逻辑
}

错误处理

插件使用统一的错误类，每个错误对象包含：

RSA 错误（RSAError）

DSA 错误（DSAError）

摘要算法错误（DigestError）

对称加密错误（SymmetricError）

import { encrypt } from '@/uni_modules/dida2-crypto'

try {
  const encrypted = await encrypt('Hello', publicKey)
} catch (e) {
  // e.message 为错误描述
  // e.code 为错误码
  // e.detail 为原始异常信息
  console.error(`Error ${e.code}: ${e.message}`)
}

典型用例

RSA 完整流程：密钥生成 → 加密 → 解密 → 签名 → 验签

import {
  generateKeyPair, encrypt, decrypt, sign, verify,
  startTime, getElapsed
} from '@/uni_modules/dida2-crypto'

// 1. 生成 RSA 2048 密钥对（PEM 格式）
const t0 = startTime()
const keyPair = await generateKeyPair(2048, { keyFormat: 'pem' })
console.log('耗时: ' + getElapsed(t0) + ' ms')

// 2. 公钥加密
const encrypted = await encrypt('Hello World', keyPair.publicKey)

// 3. 私钥解密
const decrypted = await decrypt(encrypted, keyPair.privateKey)
console.log(decrypted)  // "Hello World"

// 4. 私钥签名
const signature = await sign('Hello World', keyPair.privateKey, {
  signAlgorithm: 'SHA256withRSA'
})

// 5. 公钥验签
const isValid = await verify('Hello World', signature, keyPair.publicKey, {
  signAlgorithm: 'SHA256withRSA'
})
console.log(isValid)  // true

AES 对称加密（CBC 模式）

import {
  symmetricGenerateKey, symmetricEncrypt, symmetricDecrypt
} from '@/uni_modules/dida2-crypto'

// 1. 生成 AES-256 密钥
const keyBase64 = await symmetricGenerateKey('AES', 256)

// 2. 生成 IV（CBC 模式需要，AES 为 16 字节）
//    可使用 symmetricGenerateKey('AES', 128) 生成一个 16 字节的密钥作为 IV
const ivBase64 = await symmetricGenerateKey('AES', 128)

// 3. 加密
const encrypted = await symmetricEncrypt('Hello World', keyBase64, 'AES', {
  mode: 'CBC',
  padding: 'PKCS5Padding',
  iv: ivBase64
})

// 4. 解密
const decrypted = await symmetricDecrypt(encrypted, keyBase64, 'AES', {
  mode: 'CBC',
  padding: 'PKCS5Padding',
  iv: ivBase64
})

跨平台兼容写法

import {
  symmetricGenerateKey, symmetricEncrypt, symmetricDecrypt,
  isHarmonyOS
} from '@/uni_modules/dida2-crypto'

// 根据平台选择算法
const algorithm = isHarmonyOS ? 'AES' : 'Blowfish'
const keyBase64 = await symmetricGenerateKey(algorithm)

PBE 密码加密（仅 Android）

import { pbeEncrypt, pbeDecrypt } from '@/uni_modules/dida2-crypto'

// 加密（salt 不提供则自动生成）
const result = await pbeEncrypt('Sensitive Data', 'myPassword', 'PBEWithSHA1AndDESede', {
  iterationCount: 5000
})

// 解密（需要加密时返回的 salt 和 iterationCount）
const decrypted = await pbeDecrypt(result.encrypted, 'myPassword', 'PBEWithSHA1AndDESede', {
  salt: result.salt,
  iterationCount: result.iterationCount
})

DSA 签名验签（仅 Android）

import { dsaGenerateKeyPair, dsaSign, dsaVerify } from '@/uni_modules/dida2-crypto'

const keyPair = await dsaGenerateKeyPair(2048)
const signature = await dsaSign('Hello', keyPair.privateKey)
const isValid = await dsaVerify('Hello', signature, keyPair.publicKey)

摘要计算 + HMAC

import { digest, hmac } from '@/uni_modules/dida2-crypto'

// SHA-256 摘要（hex 格式）
const hash = await digest('Hello World', 'SHA-256')

// MD5 摘要（Base64 格式）
const md5 = await digest('Hello World', 'MD5', 'base64')

// HMAC-SHA256
const hmacValue = await hmac('Hello World', 'secretKey', 'HmacSHA256')

示例项目

本插件附带完整的测试示例项目，包含所有功能的交互式演示页面：

注意事项

1. RSA 加密数据长度限制：明文长度不能超过密钥长度减去填充字节。PKCS1 填充最多加密 keySize/8 - 11 字节，OAEP 填充更少。建议对超长数据先做对称加密，再用 RSA 加密对称密钥。
2. 对称加密 CBC 模式：必须提供 IV（初始化向量），AES 为 16 字节，DES/Blowfish/RC2 为 8 字节。
3. PBE 解密：必须提供加密时返回的 salt 和 iterationCount，否则无法解密。
4. ARCFOUR：是流密码，不支持加密模式选择，也不需要填充。
5. 密钥格式：pkcs8 为 Base64 编码的 DER 数据，pem 为带 -----BEGIN ...----- 头尾的文本格式。加解密时密钥格式需与生成时一致。
6. 性能：RSA 4096 密钥生成可能需要数秒，建议使用异步接口并在后台执行。
7. 鸿蒙平台同步 API：HarmonyOS 的 cryptoFramework 仅支持异步调用，同步 API（如 encryptSync、digestSync 等）在鸿蒙平台会抛出错误，请统一使用异步 API。
8. 鸿蒙平台 NoPadding：AES NoPadding 模式下输入数据需为 16 字节的整数倍，插件会自动进行零填充，解密时自动去除尾部补零。如原始数据本身以 \0 结尾，可能会丢失尾部零字节，建议使用 PKCS5Padding/PKCS7 填充模式。

技术参考文档

• UTS 语法
• UTS API 插件
• UTS uni-app 兼容模式组件
• UTS 标准模式组件
• Hello UTS