更新记录

1.0.0(2026-11-18)

1.0.0(2026-11-17)

首个版本。

新增 · 加密存储:secureSet / secureGet / secureRemove / listKeys / purgeExpired · 导出脱敏:sanitizeForExport(剪贴板 / 分享 / 文件 / 日志四场景)+ registerSensitiveRule 自定义规则 · 自检:selfCheck(),输出密钥保护等级、加密往返、篡改检测、脱敏管线、调试器状态 · 容器 v1:AES-256-GCM + 记录级密钥(HKDF)+ 头部 HMAC + 分块,防截断与拼接

密钥保护 · Android:AndroidKeyStore 生成 KEK(可用时在 TEE / StrongBox 内)包裹主密钥,主密钥不以明文落盘 · iOS:Keychain(设备绑定、不可迁移)

验证 · 236 项断言全部通过:三端(JS 参考实现 / Swift / Kotlin)跑同一份向量并逐字节比对 · Android 真机(Xiaomi M2104K10AC / Android 13)自检 7/7


平台兼容性

端安盾 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:插件市场导入(推荐)

  1. HBuilderX 打开项目 → 插件市场搜索 endsec → 点「下载插件并导入 HBuilderX」
  2. 选择你的项目,插件会装到 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。 这是刻意设计——调用方不该靠异常区分"过期"和"被篡改",避免泄露侧信道信息。


七、约束与注意事项

  1. key 规则:仅允许字母、数字、.、_、-;不能是 . 或 ..;最长 128 字符。用于防路径穿越。
  2. 单条 8 MB 上限:超过返回 endsec-too-large。大文件请自己分片或走文件加密。
  3. value 必须是字符串:对象先 JSON.stringify,读回来再 JSON.parse。
  4. 删除 ≠ 抹除:secureRemove 删的是记录与元数据,密钥还在时密文理论上仍可解。真抹除需整库重写。
  5. 换机即失效:密钥在 KeyStore / Keychain(设备绑定、不可迁移),重装或换机后旧密文解不开——这是预期行为,不是 bug。
  6. 主密钥永不明文落盘:由系统安全区(Android Keystore / iOS Keychain)内的 KEK 包裹。
  7. secureGet 默认开调试器检测:真机连着调试器时会返回 null,别误判成"数据丢了"。
  8. 不做国密: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 云函数模板,负责接收审计事件、抗篡改留存、导出举证材料。它不是必需的: 不装云插件,端侧加密与脱敏照样工作。

要接的话:

  1. 在 uniCloud 控制台绑定服务空间(阿里云 / 腾讯云 / 支付宝云)
  2. 上传 uniCloud/cloudfunctions/ 下的函数(endsec-audit-receiver、endsec-anchor、endsec-cleanup、endsec-selftest、endsec-evidence-export + 公共模块 endsec-common)
  3. 建索引:endsec_audit_logs / endsec_audit_anchors
  4. 部署后跑一次 endsec-selftest 自检
  5. 按云插件的 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。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无。不申请存储、网络、位置、相机、麦克风、通讯录、短信、电话状态等任何运行时权限;仅使用应用私有目录与系统密钥库(AndroidKeyStore / iOS Keychain)

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

不采集任何数据,不发起任何网络请求,服务器地址:无(无任何域名或 IP 上报)。密钥与密文仅存于本机应用私有目录与系统密钥库,加密、解密、脱敏全部在设备本地完成,不上传、不统计、不分享给任何第三方。用途:仅为本应用自身提供凭据加密存储与导出脱敏

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无。插件不含任何广告 SDK、无推广位与信息流,不展示任何广告内容。

暂无用户评论。