更新记录

1.0.2（2026-04-20）

1.0.1（2026-04-18）

• 新增鸿蒙/ iOS 端 AES、MD5、RSA、SHA、HMAC、Base64、SM2、SM3、SM4 能力

1.0.1（2026-04-18）

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

平台兼容性

uni-app(4.87)

uni-app x(4.87)

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

hl-crypto-uts 是一个基于 UTS 封装的 Android / iOS / Harmony 端加密插件，适用于 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-ios/
    │   ├── index.uts
    │   ├── Hybrid.swift
    │   ├── config.json
    │   └── Frameworks/
    ├── app-harmony/
    │   ├── index.uts
    │   ├── Hybrid.ets
    │   ├── config.json
    │   └── module.json5
    └── 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)

iOS 使用说明

如果你主要接的是 iOS 项目，可以先看这一节。

适用范围

• 支持 uni-app 的 iOS App
• 不支持 H5
• 不支持 uni-app x

iOS 端依赖

iOS 端能力分为两部分：

• AES、RSA、MD5、SHA、HMAC、Base64：使用系统安全库实现
• SM2、SM3、SM4：使用 GMObjC.xcframework + OpenSSL.xcframework

插件的 iOS 原生实现位于：

uni_modules/hl-crypto-uts/utssdk/app-ios/
├── index.uts
├── Hybrid.swift
├── config.json
└── Frameworks/
    ├── GMObjC.xcframework
    └── OpenSSL.xcframework

iOS 接入方式

1. 在页面或业务模块中导入插件：

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

2. 正常调用 API，无需区分 Android / iOS 写法：

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

if (res.code === 0) {
  console.log('摘要结果:', res.output)
} else {
  console.error('调用失败:', res.message)
}

3. 在 HBuilderX 中运行到 iOS 真机或执行云打包即可。

iOS 构建要求

• 最低部署版本：iOS 12.0
• AES/GCM 需要 iOS 13+
• RSA/NoPadding 当前 iOS 端不支持

iOS 开发注意事项

• 插件源码应修改 uni_modules/hl-crypto-uts/utssdk/app-ios/ 下的文件
• ios/uni_modules/... 属于生成产物，不建议直接修改
• 如果修改了 iOS 原生源码或 Frameworks 目录，请重新同步原生工程后再编译
• 返回值结构和 Android 保持一致，业务层一般不需要写平台分支

iOS 常见调用示例

AES 加密

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

console.log(aesRes)

SHA 摘要

const shaRes = cryptoApi.sha({
  data: 'hello ios',
  algorithm: 'SHA-256',
  outputEncoding: 'hex'
})

console.log(shaRes.output)

RSA 签名

const signRes = cryptoApi.rsaSign({
  data: 'hello ios',
  privateKey: privateKeyPem,
  algorithm: 'SHA256withRSA',
  outputEncoding: 'base64'
})

console.log(signRes)

SM2 签名

const sm2Res = cryptoApi.sm2Sign({
  data: 'hello ios',
  privateKey: sm2PrivateKey,
  userId: '1234567812345678',
  outputEncoding: 'base64'
})

console.log(sm2Res)

Harmony 使用说明

如果你接的是鸿蒙项目，可以看这一节。

适用范围

• 支持 uni-app 的 Harmony App
• 不支持 H5
• 不支持 uni-app x

Harmony 端依赖

Harmony 端当前基于官方 CryptoArchitectureKit 实现：

• 无需额外引入第三方加密库
• 无需额外集成 har / so
• 插件源码位于 uni_modules/hl-crypto-uts/utssdk/app-harmony/

对应目录如下：

uni_modules/hl-crypto-uts/utssdk/app-harmony/
├── index.uts
├── Hybrid.ets
├── config.json
└── module.json5

Harmony 接入方式

1. 在页面或业务模块中导入插件：

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

2. 正常调用 API，无需单独区分 Android / iOS / Harmony：

const res = cryptoApi.hmac({
  data: 'hello harmony',
  key: 'oauth-secret-key-16',
  algorithm: 'HmacSHA256'
})

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

Harmony 已验证能力清单

以下能力已经通过项目内 Demo 页实际回归验证：

• AES 加密 / 解密
• RSA 密钥对生成
• RSA/PKCS1Padding 公钥加密 / 私钥解密
• RSA/OAEPWithSHA-256AndMGF1Padding 公钥加密 / 私钥解密
• RSA PEM 公私钥导入
• RSA 签名 / 验签
• RSA 多摘要签名 / 验签：MD5withRSA、SHA1withRSA、SHA256withRSA、SHA512withRSA
• SM2 密钥对生成、加密 / 解密、签名 / 验签
• SM4 加密 / 解密
• MD5、SHA-256、SM3 摘要
• HMAC-SHA1、HMAC-SHA256
• Base64 编码 / 解码
• 兼容别名 *Sync API
• Base64 DER 与 PEM 格式 RSA 密钥导入

Harmony 开发注意事项

• 插件源码应修改 uni_modules/hl-crypto-uts/utssdk/app-harmony/ 下的文件
• 不建议直接修改编译生成目录
• Harmony 侧当前 SM2 userId 仅保证默认值 1234567812345678
• 如果修改了 Harmony 原生源码，建议重新编译并回归 Demo 页面

Harmony 推荐回归项

建议至少回归以下按钮场景：

• AES
• RSA
• 扩展：Base64 / HMAC
• RSA 密钥+签验+加解密
• SM2 全流程

小白快速上手

如果你只想先跑通一次，可以直接照着下面 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 / utssdk/app-ios/index.uts 负责桥接导出
4. utssdk/app-android/Hybrid.kt / utssdk/app-ios/Hybrid.swift 负责原生实现

实现上：

• Android 端的 AES、RSA、MD5、SHA 使用 JCA/JCE
• iOS 端的 AES、RSA、MD5、SHA、HMAC、Base64 使用系统安全库
• Android 端的 SM2、SM3、SM4 使用 BouncyCastle
• iOS 端的 SM2、SM3、SM4 使用 GMObjC + OpenSSL
• RSA 加密和解密支持自动分段
• 编码转换、密钥格式识别、错误结构封装都在平台侧 Hybrid 文件内统一处理

使用注意事项

1. 平台限制

• 当前支持 Android、iOS 与 Harmony
• H5 等平台仍不可用

2. 对称加密注意点

• 非 ECB 模式必须传 iv
• AES 默认使用 PKCS5Padding
• SM4 默认使用 PKCS7Padding
• 实际业务中请使用真实随机密钥和随机 iv
• iOS 上 AES/GCM 需要 iOS 13+

3. RSA 注意点

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

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 签名内部会引入随机数，因此不同次签名结果可以不同，应以验签结果为准。