更新记录

1.0.1（2026-04-18）

• 初始版本
• 新增 Android 端 AES、MD5、RSA、SHA、SM2、SM3、SM4 等能力

平台兼容性

uni-app(4.87)

uni-app x(4.87)

Android 加密解密 UTS 插件 (hl-crypto-uts)

hl-crypto-uts 是一个基于 UTS 封装的 Android 端加密插件，适用于 uni-app 项目。

如果你是第一次接触这类插件，可以先把它理解成一个“手机端加密工具箱”：

• 想把一段文字加密后再传给后端，可以用 AES、RSA、SM2、SM4
• 想算摘要，可以用 MD5、SHA、SM3
• 想做签名验签，可以用 RSA、SM2
• 想生成测试密钥，可以用 generateRsaKeyPair()、generateSm2KeyPair()

文档下面会先给出最简单的导入方式和最小调用示例，再逐步解释每个 API 的参数。

适用范围

功能清单

• 支持 AES 对称加密 / 解密
• 支持 RSA 公钥加密 / 私钥解密
• 支持 RSA 签名 / 验签
• 支持 RSA 密钥对生成
• 支持 SM2 公钥加密 / 私钥解密
• 支持 SM2 签名 / 验签
• 支持 SM2 密钥对生成
• 支持 SM4 对称加密 / 解密
• 支持 MD5、SHA、SM3 摘要
• 支持 HMAC
• 支持 Base64 编码 / 解码
• 支持 utf8、hex、base64 编码转换
• 支持 PEM、Base64 DER、十六进制密钥自动识别
• 支持兼容别名 API，便于对接其它 SDK 的 *Sync 命名

目录结构

uni_modules/hl-crypto-uts/
├── package.json
├── readme.md
└── utssdk/
    ├── interface.uts
    └── app-android/
        ├── index.uts
        ├── Hybrid.kt
        └── config.json

安装与导入

插件已位于项目 uni_modules 目录中，无需额外安装。

推荐使用和 Demo 完全一致的导入方式：

import * as cryptoApi from '@/uni_modules/hl-crypto-uts'

后面文档中的示例，也统一按这个写法来调用，例如：

const result = cryptoApi.md5({ data: 'hello' })
console.log(result.output)

小白快速上手

如果你只想先跑通一次，可以直接照着下面 3 步：

第 1 步：导入插件

import * as cryptoApi from '@/uni_modules/hl-crypto-uts'

第 2 步：调用一个最简单的 API

const res = cryptoApi.md5({ data: 'hello' })
console.log(res)

正常情况下你会得到类似这样的返回：

{
  code: 0,
  message: 'MD5 操作成功',
  output: '5d41402abc4b2a76b9719d911017c592',
  algorithm: 'MD5',
  transformation: 'MD5'
}

第 3 步：看 code 判断有没有成功

• code === 0：表示成功
• code !== 0：表示失败，此时优先看 message

业务里最常见的写法就是：

const res = cryptoApi.sha({ data: 'hello', algorithm: 'SHA-256' })

if (res.code === 0) {
  console.log('结果:', res.output)
} else {
  console.error('失败原因:', res.message)
}

页面 Demo

项目内已提供调用示例页面：

• pages/crypto-demo/index.vue

该页面覆盖了以下测试场景：

• AES 加解密
• RSA 加解密
• MD5 / SHA / SM3 摘要
• SM4 加解密
• SM2 加解密
• Base64 编解码
• HMAC
• RSA 密钥生成、签名、验签、多摘要签验
• SM2 密钥生成、签名、验签、兼容别名 API

建议先运行 Demo，再按业务场景替换密钥、算法和编码方式。

如果你刚开始接触这些算法，推荐按这个顺序理解：

1. 先看 Base64，它只是编码转换，不是加密
2. 再看 MD5 / SHA / SM3，它们是摘要，不能解密回去
3. 再看 AES / SM4，它们是对称加密，通常需要 key，有时还需要 iv
4. 最后看 RSA / SM2，它们是非对称加密，通常会涉及公钥、私钥、签名、验签

返回结构

大多数 API 都返回统一的 CryptoResult。

如果你不熟悉这些字段，可以先这样理解：

• code：这次调用成功还是失败
• message：成功或失败的文字说明
• output：真正的结果
• algorithm：本次使用的算法名
• transformation：本次使用的算法模式或变换字符串

验签接口返回 VerifyResult：

密钥生成接口返回 KeyPairResult：

编码规则

插件内部统一支持以下编码值：

• utf8
• hex
• base64

常见默认值如下：

密钥格式说明

RSA

支持以下公钥格式：

• PEM
• X509 DER 的 Base64
• PKCS1 公钥

支持以下私钥格式：

• PEM
• PKCS8 DER 的 Base64
• PKCS1 私钥

SM2

支持以下公钥格式：

• 原始十六进制公钥 04 + X + Y
• 原始十六进制公钥 X + Y
• DER / PEM 公钥

支持以下私钥格式：

• 64 位十六进制私钥
• DER / PEM 私钥

generateSm2KeyPair() 返回值中：

• publicKey 为未压缩十六进制公钥，通常以 04 开头
• privateKey 为 64 位十六进制私钥

API 列表

1. AES / SM4

aesEncrypt(options)

aesDecrypt(options)

sm4Encrypt(options) / sm4Decrypt(options)

参数结构与 AES 基本一致，默认 transformation 为 SM4/ECB/PKCS7Padding。

2. 摘要

md5(options)

sha(options)

sm3(options)

参数结构与 md5 一致。

3. Base64

base64Encode(options)

base64Decode(options)

4. HMAC

hmac(options)

5. RSA

rsaEncrypt(options)

rsaDecrypt(options)

rsaSign(options)

rsaVerify(options)

generateRsaKeyPair(options)

6. SM2

sm2Encrypt(options)

sm2Decrypt(options)

sm2Sign(options)

sm2Verify(options)

generateSm2KeyPair()

无参数，直接返回 SM2 十六进制公私钥。

7. 兼容别名 API

以下方法与主 API 语义一致，主要用于兼容其它 SDK 命名：

说明：

• SM2 签名内部包含随机数，因此同样的数据和私钥，多次签名输出不一定相同
• 对于 SM2 兼容别名，应以“签名成功且验签通过”为准，而不是比较签名字符串是否完全一致

示例代码

AES 加解密

const aesResult = cryptoApi.aesEncrypt({
  plainText: 'hello uts',
  key: '1234567890abcdef',
  iv: 'abcdef1234567890',
  transformation: 'AES/CBC/PKCS5Padding'
})

if (aesResult.code === 0) {
  const aesPlain = cryptoApi.aesDecrypt({
    cipherText: aesResult.output || '',
    key: '1234567890abcdef',
    iv: 'abcdef1234567890',
    transformation: 'AES/CBC/PKCS5Padding'
  })
  console.log(aesPlain.output)
}

摘要

console.log(cryptoApi.md5({ data: 'hello' }).output)
console.log(cryptoApi.sha({ data: 'hello', algorithm: 'SHA-256' }).output)
console.log(cryptoApi.sm3({ data: 'hello' }).output)

RSA 加解密

const kp = cryptoApi.generateRsaKeyPair({ keySize: 2048 })

const enc = cryptoApi.rsaEncrypt({
  plainText: 'rsa message',
  publicKey: kp.publicKey
})

const dec = cryptoApi.rsaDecrypt({
  cipherText: enc.output || '',
  privateKey: kp.privateKey
})

RSA 签名验签

const sign = cryptoApi.rsaSign({
  data: 'hello sign',
  privateKey: kp.privateKey,
  algorithm: 'SHA256withRSA'
})

const verify = cryptoApi.rsaVerify({
  data: 'hello sign',
  publicKey: kp.publicKey,
  signature: sign.output || '',
  algorithm: 'SHA256withRSA'
})

SM2 加解密

const sm2Kp = cryptoApi.generateSm2KeyPair()

const sm2Enc = cryptoApi.sm2Encrypt({
  plainText: '国密测试',
  publicKey: sm2Kp.publicKey,
  mode: 'C1C3C2',
  outputEncoding: 'hex'
})

const sm2Dec = cryptoApi.sm2Decrypt({
  cipherText: sm2Enc.output || '',
  privateKey: sm2Kp.privateKey,
  mode: 'C1C3C2',
  inputEncoding: 'hex',
  outputEncoding: 'utf8'
})

SM2 签名验签

const sm2SignResult = cryptoApi.sm2Sign({
  data: 'sm2 sign demo',
  privateKey: sm2Kp.privateKey
})

const sm2VerifyResult = cryptoApi.sm2Verify({
  data: 'sm2 sign demo',
  publicKey: sm2Kp.publicKey,
  signature: sm2SignResult.output || ''
})

Base64 和 HMAC

const b64 = cryptoApi.base64Encode({ data: 'hello', encoding: 'utf8' })
const raw = cryptoApi.base64Decode({ data: b64.output || '', encoding: 'utf8' })

const h = cryptoApi.hmac({
  data: 'hello',
  key: 'secret',
  algorithm: 'HmacSHA256',
  outputEncoding: 'hex'
})

实现说明

插件调用链如下：

1. 页面或业务代码调用 uni_modules/hl-crypto-uts
2. utssdk/interface.uts 定义 UTS 类型和 API
3. utssdk/app-android/index.uts 负责桥接导出
4. utssdk/app-android/Hybrid.kt 负责 Android 原生实现

实现上：

• AES、RSA、MD5、SHA 使用 Android JCA/JCE
• SM2、SM3、SM4 使用 BouncyCastle
• RSA 加密和解密支持自动分段
• 编码转换、密钥格式识别、错误结构封装都在 Hybrid.kt 内统一处理

使用注意事项

1. 平台限制

• 当前仅实现 Android
• 在非 Android 平台调用会不可用

2. 对称加密注意点

• 非 ECB 模式必须传 iv
• AES 默认使用 PKCS5Padding
• SM4 默认使用 PKCS7Padding
• 实际业务中请使用真实随机密钥和随机 iv

3. RSA 注意点

• 默认变换为 RSA/ECB/PKCS1Padding
• 长文本会自动分段处理
• Demo 中 1024 位密钥仅用于快速验证，正式环境建议至少 2048 位

4. SM2 注意点

• mode 需在加解密两端保持一致
• userId 需在签名验签两端保持一致
• SM2 签名输出可能每次不同，只要验签通过即为正常

5. 摘要算法注意点

• MD5、SHA、SM3 是摘要算法，不能还原明文

常见问题

Q1: 为什么 AES / SM4 解密提示需要 iv？

只要使用的是非 ECB 模式，例如 CBC 或 GCM，就必须传入正确的 iv。

Q2: 为什么 RSA 解密失败？

通常由以下原因导致：

• 公私钥不匹配
• transformation 不一致
• 密文编码方式不一致
• 服务端和客户端使用的密钥格式不同

Q3: 为什么 SM2 提示 Invalid point coordinates？

通常说明传入的 SM2 公钥不是合法曲线点，常见原因包括：

• 十六进制公钥内容损坏
• 公钥长度不正确
• 误把其它曲线的公钥当成 SM2 公钥使用
• 04 + X + Y / X + Y 格式写错

建议优先使用 generateSm2KeyPair() 生成的公私钥进行本地自测，再替换为业务侧密钥。

Q4: 为什么两次 SM2 签名结果不一样？

这是正常现象。SM2 签名内部会引入随机数，因此不同次签名结果可以不同，应以验签结果为准。

依赖说明

• 最低 Android SDK 版本：21
• 建议在 Android 构建环境中确保可用的 BouncyCastle 依赖，以支持 SM2、SM3、SM4 等能力