封装的功能

MQTT 封装

NativeScript 使用经验

其他

Keystore 与 AES-GCM

@ajax-js/nativescript-common 在 Android 8.0+ 使用 Android Keystore 保存密钥、Cipher 执行 AES-GCM;在 iOS 15+ 使用 Keychain 保存密钥、CryptoKit 执行 AES-GCM。两端共用 TS 接口和消息格式,支持无 AAD 的旧方法及带 AAD 的新方法。

安装与原生产物构建、发布步骤见 common README。npm 包携带 Android JAR、真机及模拟器 XCFramework、TS 产物和声明文件。升级 AAD 接口须同时更新原生产物并重新构建 App,不能只更新 TS。

接口概览

方法 参数 返回值与失败条件
importAesKey(alias, keyBase64) 非空白别名,最多 128 个 UTF-16 单元;Base64 密钥解码后为 16、24 或 32 字节 void;无效参数、同名别名或原生存储失败时抛出异常
hasAesKey(alias) 相同别名规则 boolean;无效别名或查询失败时抛出异常;存在不保证后续操作成功
deleteAesKey(alias) 相同别名规则 void;不存在时成功,无效别名或删除失败时抛出异常
encryptJson(alias, value) 已导入的密钥别名、可 JSON 序列化的值 EncryptedBody;序列化、查找密钥或加密失败时抛出异常
decryptJson<T>(alias, body) 已导入的别名、nonce/data 消息体 T,默认 unknown;消息体、认证、密钥或 JSON 解析错误时抛出异常
encryptJsonWithAssociatedData(alias, value, associatedData) 前述加密参数及原样 AAD 字符串 EncryptedBody;AAD 非字符串或加密失败时抛出异常
decryptJsonWithAssociatedData<T>(alias, body, associatedData) 前述解密参数及完全相同的 AAD 字符串 T;AAD 无效、不一致或其他解密错误时抛出异常,不返回明文
provisionAesKey(options) HTTPS 地址、JWT、可选正数超时毫秒数 Promise<{ keyId, alias }>;请求、响应验证或导入失败时拒绝

这些接口在不支持的平台调用会抛出异常。JSON.stringify 的规则适用于加密输入:对象中的 undefined 属性会被省略,循环引用、BigInt 和顶层 undefined 等会失败;泛型只提供类型声明,不验证业务结构。

Keystore 与 JSON API

import { importAesKey, hasAesKey, deleteAesKey, encryptJson, decryptJson, type EncryptedBody } from '@ajax-js/nativescript-common';

/*
 * alias 是业务保存的密钥别名;keyBase64 是调用方提供的标准 Base64 AES 密钥。
 */
const alias = 'ajaxjs.aes.demo-v1';
importAesKey(alias, keyBase64);
const exists = hasAesKey(alias);
const encrypted: EncryptedBody = encryptJson(alias, { message: '你好' });
const value = decryptJson<{ message: string }>(alias, encrypted);
deleteAesKey(alias);

keyBase64 由应用提供,为 16、24 或 32 字节 AES 密钥的标准 Base64。同名别名已存在时拒绝导入,轮换密钥应使用新别名。应用可在登录后通过自己的 HTTPS 接口获取密钥,再调用 importAesKey;也可使用上面的可选 provisionAesKey。

encryptJson 返回 { nonce, data }:nonce 为 12 字节,data 包含密文及 16 字节 GCM 标签,两者均为 Base64。 Android 使用 Cipher 和 Keystore;iOS 使用 CryptoKit 和 Keychain(WhenUnlockedThisDeviceOnly,不同步),不提供密钥导出 API;认证失败、缺少密钥或无效输入会抛出异常。 decryptJson 的泛型仅提供类型断言,业务对象应由应用校验。 原有方法不传入 AAD;新增 AAD 方法见下节。消息体仍不包含 keyId 或防重放机制,业务需自行设计密钥版本映射和重放检测,时间戳不能单独防重放。 不支持的平台会明确报错。普通导入不保证所有设备都具备硬件密钥保护。

已有 /aes 子路径仍保留原来的 @noble/ciphers API,需要显式传入密钥,不使用 Keystore。

附加认证数据(AAD)

原有 encryptJson、decryptJson 保持兼容。新增方法使用字符串形式的 AAD,Android/iOS 均按 UTF-8 编码,不自动规范化或序列化。

import { encryptJsonWithAssociatedData, decryptJsonWithAssociatedData } from '@ajax-js/nativescript-common';

const aad = '  device-123/消息/v1 🔐  ';
const body = encryptJsonWithAssociatedData(alias, { message: '你好' }, aad);
const value = decryptJsonWithAssociatedData<{ message: string }>(alias, body, aad);

AAD 只参与认证,不加密,也不会自动放入返回的 { nonce, data }。调用方负责传输或重建相同 AAD。非空 AAD 消息用旧方法解密、或者使用不同 AAD 时均认证失败,不返回明文。空字符串等同无 AAD,可与旧方法双向兼容。不得将 null/undefined 当作空字符串传入。

新增接口需要更新对应原生 JAR/XCFramework;仅更新 TS 无法调用旧原生组件中不存在的方法。

消息格式

interface EncryptedBody {
    nonce: string;
    data: string;
}

两端均使用标准 Base64:nonce 解码后为 12 字节;data 为密文后接 16 字节 GCM 认证标签,解码后至少 16 字节。每次加密生成新 nonce,接收方必须保存或传输原始 nonce 和完整 data,不应自行丢弃标签。

AAD 是认证输入,不是保密内容。必须由调用方传输或重建完全一致的 UTF-8 字节,包括前后空格、换行、大小写及 Unicode 表示;组件不进行 trim、Unicode 规范化或对象序列化。不要把含有秘密的信息放入需要公开传输的 AAD。

新旧方法兼容性

加密方式 解密方式 结果
非空 Unicode AAD 相同 AAD 的新方法 成功
非空 AAD 不同 AAD 的新方法 认证失败
非空 AAD 旧方法 认证失败
旧方法 旧方法 成功
旧方法 空字符串 AAD 的新方法 成功
空字符串 AAD 的新方法 旧方法 成功

机器人一机一密:HKDF-SHA256

新增 deriveRobotAesKey(masterKeyBase64, robotMac): string 返回设备密钥的标准 Base64; deriveAndImportRobotAesKey(alias, masterKeyBase64, robotMac): void 在原生侧派生并导入安全存储,不向 JS 返回设备密钥。 两个接口均支持 Android/iOS,参数无效、不支持的平台、旧原生组件或原生操作失败会抛出异常;直接导入还会拒绝重复别名。 normalizeRobotMac(robotMac): string 可单独规范化 MAC,ROBOT_KEY_DERIVATION_V2 导出固定协议参数。

v2 字节协议

机器人 MQTT 报文使用 ver: 2;此前已确定的 ver: 1 保持原定义。v2 的 salt 使用版本后缀 /v2,info 仅包含标准化 MAC。通用 AES 接口仍返回 {nonce, data},由 MQTT 业务层添加并校验 ver 和 timestamp。

项目 精确定义
算法 RFC 5869 HKDF-SHA256,完整 Extract + Expand
IKM 主密钥的原始字节:规范标准 Base64 解码后为 16/24/32 字节,必须为安全随机秘密,不能是简单密码
robotMac 本协议约定机器人稳定的 Wi-Fi STA MAC,不是手机 MAC、SoftAP MAC 或 BLE MAC;接口不自行读取硬件地址
MAC 编码 接受 12 位十六进制或六个字节用一致冒号/连字符分隔;仅 ASCII 十六进制,禁止空白及混用分隔符;转为小写无分隔符,保留前导零
salt UTF8("ajaxjs/robot/key-derivation/v2"),固定公开字符串,不是随机 nonce
info UTF8(normalizedMac),仅 12 个 ASCII 字符,不使用前缀或 MAC 的 6 个原始字节
输出 32 字节 AES-256 密钥;TS 返回形式为 44 字符标准 Base64,包含 = 填充

所有字符串均不含 NUL 结尾,不 trim,不对主密钥字符串做 URL-safe Base64 转换、补填充、哈希或截断。相同主密钥与 MAC 必须产生相同输出,topic 不参与派生,仅作为后续 AES-GCM 的 AAD。

import { deriveAndImportRobotAesKey, normalizeRobotMac,
    encryptJsonWithAssociatedData, decryptJsonWithAssociatedData }
    from '@ajax-js/nativescript-common';

/*
 * masterKeyBase64 由受控配置提供,为秘密主密钥;不要记录或提交真实值。
 */
const mac = normalizeRobotMac('AA:BB:CC:DD:EE:FF');
const alias = `ajaxjs.aes.robot-v2.${mac}`;
deriveAndImportRobotAesKey(alias, masterKeyBase64, mac);
const topic = `robot/${mac}/command`;
const body = encryptJsonWithAssociatedData(alias, { command: 'stop' }, topic);
const envelope = { ver: 2, timestamp: Date.now(), ...body };
const value = decryptJsonWithAssociatedData(alias, envelope, topic);

上例首次导入使用新别名;已有别名拒绝覆盖。主密钥轮换应使用新的别名版本,并在业务侧保存所对应的主密钥版本;库不自动覆盖或判断已有别名是否与当前主密钥一致。

MAC 是公开设备标识,秘密来自主密钥。若每个客户端都持有相同主密钥,任何一处主密钥泄漏都影响全部设备;更强隔离需要在服务端或生产配置阶段派生,再仅分发设备密钥。主密钥经过 JS/原生内存,直接导入接口减少派生密钥在 JS 中暴露,但不保证全部临时副本立即擦除,也不持久化主密钥。

公开互通向量

以下主密钥仅用于测试,原始字节为 00 01 … 1f,不能用于真实机器人。

{
  "masterKeyBase64": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=",
  "robotMac": "aabbccddeeff",
  "derivedKeyHex": "ab46f491645c7e09d90c1372c999b1b88e12369d4f5aeb3e5c264e3ce6de9277",
  "derivedKeyBase64": "q0b0kWRcfgnZDBNyyZmxuI4SNp1PWus+XCZOPObeknc="
}

完整向量(包含三种主密钥长度、前导零 MAC 和不同 MAC)见 robot-key-v2.json,也随 npm 包的 test-vectors 目录发布。 Android 使用 HmacSHA256 执行 HKDF,iOS 使用 CryptoKit HKDF;基于 RFC 5869。

JWT 领取并导入密钥

import { provisionAesKey } from '@ajax-js/nativescript-common';

const result = await provisionAesKey({
  endpoint: 'https://your-server.example/api/aes-key',
  jwt: token
});

协议为 HTTPS GET,Authorization: Bearer JWT,默认超时 15 秒,不跟随重定向。 服务端须验证 JWT、授权领取,并建议返回 Cache-Control: no-store。 成功响应为 { "keyId": "aes-v1", "key": "标准 Base64 密钥" }。 keyId 限定为 1–96 个字母、数字、点、下划线或连字符;密钥长度为 16、24 或 32 字节。 返回 { keyId, alias },alias 为 ajaxjs.aes.<keyId>,不向业务层返回密钥。 同名 alias 已存在时拒绝导入;轮换使用新 keyId。再次启动可根据已保存的非秘密 alias 调用 hasAesKey。

密钥请求和导入经过 JS 及 Java/Swift 内存。代码不记录密钥或 JWT,不写入文件;清理引用不能保证立即擦除字符串。 登录及 MQTT 不由此包管理。应用在密钥导入成功后再连接 MQTT。

密钥生命周期与平台差异

业务可以直接传入密钥,不必使用 HTTPS 领取接口。原生组件不提供导出密钥的方法;同名别名拒绝覆盖,轮换时使用新别名并保存相应的非秘密密钥版本信息。删除后,旧密文只有重新导入相同密钥才可解密。

Android 清缓存通常保留密钥,清除应用数据或卸载后需要重新配置。iOS 使用 WhenUnlockedThisDeviceOnly、禁用同步的 Keychain 条目,锁屏时可能不可访问;卸载后条目可能保留,不能依靠卸载清理密钥。

密钥暂时经过 JS 及 Java/Swift 内存,清除引用不能保证所有字符串或数据副本立即擦除。普通 Android 导入不保证硬件保护,iOS AES 密钥不使用 Secure Enclave。不应记录或自行持久化原始密钥和 JWT。

Android 使用 HTTPS 领取接口时宿主需声明 INTERNET;联网状态工具另需 ACCESS_NETWORK_STATE,均无需运行时权限申请。登录、JWT 刷新、MQTT 连接及重放防护由业务负责。

demo 验证

demo 底部“测试”tab → “AES 加解密测试”提供 HTTPS/JWT 领取、直接导入、检查/删除及新旧 JSON 加解密按钮,保留底部 tabs。JWT 和密钥输入在操作结束后清空。

先点击“运行 AAD 与旧方式兼容测试”,确认上述六项兼容结果全部通过;再点击“运行本地加解密验证(含 AAD)”,确认日志 AES_SELF_CHECK:PASS。测试使用公开临时密钥,结束后删除并重新查询,清理通过记录 AES_TEST_KEY_CLEANUP:PASS:<测试别名>。

输入框验证应使用带前后空格的 AAD:相同字符串解密成功,修改或移除空格后认证失败,页面清除之前的明文;恢复原始字符串后再次成功。输入框不能自动 trim 或规范化 AAD。

2026-10-12 已在 iPhone 17 Pro / iOS 26.5 模拟器通过 3 项 XCTest UI 测试,覆盖六项兼容检查、完整自检、空格输入和认证失败后清除明文;临时密钥及界面手动导入的测试密钥均确认清理。该次流程通过 XCTest 实际点击和输入完成,未进行真机验证。运行步骤及详细记录见 demo 文档。

iOS 验证与互通

使用现有 demo 的 AES 页面运行本地验证:导入、重复拒绝、中文往返、随机 nonce、篡改拒绝、删除和删除后拒绝解密。 页面同时解密由 Android 原始 JsonBodyCipher 在 JVM 生成的 128/192/256-bit 公共测试向量,并输出 AES_INTEROP 供反向 JVM 验证。 ios/nativescipt-common/tests/Interop.java 使用生产 Cipher 代码生成/解密消息;只使用全零公开测试密钥,不能用于真实数据。

iOS Keychain 在锁屏时可能不可访问;卸载后可能保留条目,退出登录时按业务要求显式删除。 原始密钥经过 JS/Swift 内存,清除引用无法保证全部副本立即擦除。iOS AES 密钥不使用 Secure Enclave。 原生接口参考 iOS 工程说明。

桥接方式遵循 NativeScript 原生插件说明, AES 实现使用 Apple CryptoKit AES.GCM。

已验证(2026-10-10):TS/桥接测试 6 项、Android JVM 测试 8 项、真机/模拟器 XCFramework 构建、 完整 npm pack、demo Vue 类型检查、iOS 模拟器编译运行,以及生产 Android Cipher 与 CryptoKit 的 AES-128/192/256 双向互通。

Android 原生桥接与 API 白名单

如果出现 Cannot read properties of undefined (reading 'android'),应先检查原生桥接,不是直接判定为 AES 密钥或 AAD 错误。APK 包含 JAR 类不代表 NativeScript 已生成它们的桥接元数据。

启用了 App_Resources/Android/native-api-usage.json 的宿主,应保留现有配置,并在 whitelist 中加入 com.ajaxjs.nativescript.android*:*。旧工具包 com.ajaxjs.android*:* 与 common 插件的新包名不同,不能互相替代。

common 插件也提供 platforms/android/native-api-usage.json,通过 uses 声明其原生包;宿主设置 whitelist-plugins-usages: true 时可自动合并。修改白名单后重新构建并安装 Android App,仅刷新 JS 不会更新桥接元数据。原生桥接缺失时,统一 AES 接口会抛出明确的桥接配置错误。

Keystore 的查询、导入及加解密接口均为同步调用。使用固定本地密钥时,初始化应同步执行并放在同一个 try/catch 内;若将来通过网络取得密钥,应在处理 MQTT 消息前等待初始化完成,不能直接调用未等待的 async 初始化。