更新记录
1.0.0(2026-11-18)
1.0.0(2026-11-17) · 加密存储内核:secureSet / secureGet / secureRemove / selfCheck / version · 记录级 AES-256-GCM,含头部 HMAC 与块级绑定:改头、截断、换位置都会被拒 · 与付费版共用容器格式 ENDSEC01 v1 —— 升级到付费版后,历史密文可直接读取 · 不联网、不申请任何权限
平台兼容性
端安盾 endsec · 使用说明
覆盖三个插件:
endsec-uts(付费:加密存储 + 导出脱敏)、endsec-lite(免费:仅加密存储)、endsec-cloud(uniCloud 审计举证)。 版本 1.0.0 · 适用于 HBuilderX 4.71 及以上(实测 5.34)
一、环境要求
| 项 | 要求 |
|---|---|
| HBuilderX | 4.71 及以上(平台兼容性新规范自 4.71 起,低于它读不懂插件的平台矩阵) |
| 平台 | Android、iOS(App 端);Web 与小程序不支持 |
| 框架 | uni-app(vue2 / vue3 / nvue)与 uni-app x |
| 付费包运行方式 | 必须云打包自定义基座(加密 uts 插件不支持离线打包与安心打包,官方限制) |
Web / H5 没有 KeyStore / Keychain,插件会直接报错——这是设计如此,不提供"网页降级"。
二、安装
方式 1:插件市场导入(推荐)
- HBuilderX 打开项目 → 插件市场搜索
endsec→ 点「下载插件并导入 HBuilderX」 - 选择你的项目,插件会装到
uni_modules/endsec-uts/(免费版是endsec-lite)
方式 2:手动放入
把插件目录整个拷进项目的 uni_modules/ 下,最终结构必须是:
你的项目/
└── uni_modules/
└── endsec-uts/
├── package.json
├── readme.md
└── utssdk/…
安装后必须做的一步
重新制作自定义基座。原生代码(Kotlin / Swift)在打包时编入基座,标准基座里没有它——
不重做基座,运行时会报 endsec-not-inited 或方法不存在。
三、最小可用示例
import { secureSet, secureGet, secureRemove } from '@/uni_modules/endsec-uts'
// 写
const w = await secureSet('auth.token', token, {
credentialClass: 'token', // token | business,默认 business
ttlSeconds: 3600 // 1 小时后过期;0 或不传表示不过期
})
if (!w.ok) {
console.error(w.errorCode, w.message) // 例如 endsec-too-large
}
// 读:不存在 / 已过期 / 被篡改 / 换机 → 返回 null(不抛错)
const t = await secureGet('auth.token')
if (t == null) {
// 需要重新登录
}
// 删
await secureRemove('auth.token')
四、API
4.1 加密存储
| 方法 | 返回 | 说明 |
|---|---|---|
secureSet(key, value, options?) |
Promise<{ ok, errorCode, message }> |
写入。value 必须是 string,对象请先 JSON.stringify |
secureGet(key, options?) |
Promise<string \| null> |
读取校验后返回明文;任何校验失败都返回 null,不返回半截数据 |
secureRemove(key) |
Promise<boolean> |
删除记录 |
listKeys() |
Promise<string[]> |
只列 key,不返回内容 |
purgeExpired() |
Promise<number> |
清理已过期记录,返回清理条数 |
selfCheck() |
Promise<UTSJSONObject> |
运行期自检(密钥、往返、篡改、脱敏管线、调试器状态) |
version() |
string |
插件版本,便于把审计事件与版本绑定 |
secureSet 的 options
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
algorithm |
'AES-256-GCM' \| 'SM4-CBC' |
AES-256-GCM |
v1 只实现 AES-256-GCM,传 SM4 返回 endsec-algorithm-unsupported |
credentialClass |
'token' \| 'business' |
business |
数据等级,便于按等级设 TTL 与策略 |
ttlSeconds |
number | 0 |
过期秒数,上限 365 天 |
detectDebugger |
boolean | false |
写入时检测调试器,命中则拒绝 |
secureGet 的 options
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
detectDebugger |
boolean | true |
读取默认开检测——这条路径最容易被断点抓明文;命中返回 null |
4.2 导出脱敏(仅付费版)
| 方法 | 返回 | 说明 |
|---|---|---|
sanitizeForExport(data, scene, options?) |
{ data, hits, sanitizedFieldCount, scene } |
返回新对象,不改入参 |
registerSensitiveRule({ name, pattern }) |
boolean |
注册自定义规则(正则字符串),最多 32 条,仅对 sanitizeForExport 生效 |
scene 取值:'clipboard' | 'share' | 'file' | 'log',场景决定脱敏强度。
options
| 字段 | 类型 | 说明 |
|---|---|---|
keep |
string[] |
白名单路径,原样保留,如 ['createdAt', 'userId'] |
redact |
string[] |
强制脱敏的字段路径 |
判定顺序(四层,先命中先生效):显式 redact > 字段名注册表(HMAC 哈希匹配)> 值形态正则 > 自定义规则。
import { sanitizeForExport, registerSensitiveRule } from '@/uni_modules/endsec-uts'
registerSensitiveRule({ name: 'internal-ticket', pattern: 'TK\\d{6}' })
const safe = sanitizeForExport(order, 'clipboard', {
keep: ['createdAt', 'orderId']
})
uni.setClipboardData({ data: JSON.stringify(safe.data) })
console.log(safe.hits) // { phone: 2, idCard: 1, … }
console.log(safe.sanitizedFieldCount) // 共处理了多少字段/字符串
五、四个典型场景
5.1 登录态(token)
await secureSet('auth.token', token, { credentialClass: 'token', ttlSeconds: 7 * 86400 })
const t = await secureGet('auth.token')
5.2 业务数据落盘
await secureSet('biz.order.last', JSON.stringify(order), { credentialClass: 'business' })
const raw = await secureGet('biz.order.last')
const order = raw ? JSON.parse(raw) : null
5.3 导出前脱敏(售后把数据贴进工单)
const safe = sanitizeForExport(order, 'clipboard')
uni.setClipboardData({ data: JSON.stringify(safe.data) })
uni.showToast({ title: `已脱敏 ${safe.sanitizedFieldCount} 处`, icon: 'none' })
5.4 启动时自检 + 过期清理
onLaunch(async () => {
const r = await selfCheck()
console.log('selfCheck', r) // 含密钥保护等级,别对外宣称"硬件级"直到亲眼看到 TEE
await purgeExpired() // 顺手清掉过期记录
})
六、错误码
secureSet 失败时返回 { ok: false, errorCode, message }:
| errorCode | 含义 | 处理 |
|---|---|---|
endsec-arg-invalid |
参数非法(key 为空 / 超 128 字符 / 含非法字符 / TTL 越界) | 修调用方 |
endsec-too-large |
单条数据超过 8 MB | 拆分,或改存文件 |
endsec-algorithm-unsupported |
传了 SM4-CBC |
v1 只支持 AES-256-GCM |
endsec-debug-detected |
检测到调试器,拒绝写入 | 关掉调试器(生产环境正常) |
endsec-internal |
其他内部错误 | 带日志反馈 |
secureGet / secureRemove 不报错:读失败一律 null,删失败一律 false。
这是刻意设计——调用方不该靠异常区分"过期"和"被篡改",避免泄露侧信道信息。
七、约束与注意事项
- key 规则:仅允许字母、数字、
.、_、-;不能是.或..;最长 128 字符。用于防路径穿越。 - 单条 8 MB 上限:超过返回
endsec-too-large。大文件请自己分片或走文件加密。 value必须是字符串:对象先JSON.stringify,读回来再JSON.parse。- 删除 ≠ 抹除:
secureRemove删的是记录与元数据,密钥还在时密文理论上仍可解。真抹除需整库重写。 - 换机即失效:密钥在 KeyStore / Keychain(设备绑定、不可迁移),重装或换机后旧密文解不开——这是预期行为,不是 bug。
- 主密钥永不明文落盘:由系统安全区(Android Keystore / iOS Keychain)内的 KEK 包裹。
secureGet默认开调试器检测:真机连着调试器时会返回null,别误判成"数据丢了"。- 不做国密:
SM4-CBC返回不支持。自研 SM4 在密评场景下不仅不加分,反而因"未使用通过认证的密码模块"被扣分。
八、免费版(endsec-lite)与付费版的差别
| 能力 | 免费版 endsec-lite |
付费版 endsec-uts |
|---|---|---|
secureSet / secureGet / secureRemove |
✅ | ✅ |
listKeys / purgeExpired |
❌ 没有 | ✅ |
selfCheck / version |
✅ | ✅ |
sanitizeForExport(四场景脱敏) |
❌ | ✅ |
registerSensitiveRule(自定义规则) |
❌ | ✅ |
| 容器格式 | ENDSEC01 v1 |
ENDSEC01 v1(同一套) |
免费版与付费版的 import 路径不同(@/uni_modules/endsec-lite),但两者共用同一把主密钥与同一个存储目录
(KEK 别名同为 endsec_kek_v1,数据目录同为 endsec),容器格式也同为 ENDSEC01 v1。这意味着:
- 升级到付费版时,历史密文可以直接读——只要把 import 换成
@/uni_modules/endsec-uts即可,不需要迁移脚本。 - 反过来说,两个包装在同一工程里时,key 是共享的:同名 key 会互相覆盖/读到对方写的数据。这是特性不是 bug, 但别在同一工程里把两包当作"两个独立存储空间"来设计。
- 卸载/清空数据时,删任一个包的记录都会影响另一个包看到的同一份数据。
九、与云插件配合(可选)
endsec-cloud 是 uniCloud 云函数模板,负责接收审计事件、抗篡改留存、导出举证材料。它不是必需的:
不装云插件,端侧加密与脱敏照样工作。
要接的话:
- 在 uniCloud 控制台绑定服务空间(阿里云 / 腾讯云 / 支付宝云)
- 上传
uniCloud/cloudfunctions/下的函数(endsec-audit-receiver、endsec-anchor、endsec-cleanup、endsec-selftest、endsec-evidence-export+ 公共模块endsec-common) - 建索引:
endsec_audit_logs/endsec_audit_anchors - 部署后跑一次
endsec-selftest自检 - 按云插件的
readme.md第 4 节协议,把端侧事件签名后上送
十、常见问题
Q:报 endsec-not-inited 或"方法不存在"?
自定义基座没带上插件。重新制作基座(见第二节)。
Q:secureGet 一直返回 null?
按顺序排查:key 是否写对 → 是否已过期 → 是否被抓包/调试器(默认检测)→ 是否重装或换机过 → 数据是否被外部篡改(会静默返回 null)。
Q:能存二进制 / 图片吗? 可以,但要自己转 base64 后当字符串存,注意 8 MB 上限(base64 会放大约 1.33 倍)。
Q:能跨设备同步吗? 不能。密钥与设备绑定,这是安全设计,不是缺陷。要跨设备就加密后存云端,或走你自己的密钥托管方案。
Q:支持 Web / 小程序吗? 不支持,见第一节。
Q:怎么确认真的防篡改?
跑 selfCheck(),或直接用示例工程:改密文文件里的一个字节,再 secureGet,应返回 null。

收藏人数:
购买源码授权版(
试用
使用 HBuilderX 导入示例项目
赞赏(0)
下载 0
赞赏 0
下载 12772290
赞赏 1959
赞赏
京公网安备:11010802035340号