MiniAppProxy 实现类中覆写 getDeviceKey(实现类通常继承 BaseMiniAppProxyImpl,并通过 @ProxyService 注解注册):@Overridepublic boolean getDeviceKey(DeviceKeyRequest request, DeviceKeyCallback callback) {// 由 superapp 自行实现:向自有后台请求设备密钥,并通过 callback 回传}
返回值 | 含义 | 后续行为 |
true | 当前宿主启用签名能力,由宿主代理设备密钥的获取 | SDK 等待 callback 的回调结果;密钥到位后请求携带签名 |
false | 当前宿主不启用签名能力 | SDK 丢弃 callback,请求不携带签名,后续不再回调该接口 |
true 时,必须在所有分支(成功、后台返回失败、本地异常)最终回调 callback 一次;若长时间未回调,SDK 将按本次获取失败处理,请求不中断。DeviceKeyRequest 提供以下入参,供宿主组装请求:参数 | 来源 | 说明 |
uuid | request.uuid | 设备唯一标识,SDK 生成并持久化,多进程共用同一值 |
appId | request.appId | 后台分配的应用 ID |
customId | request.customId | 租户 ID |
sdkVersion | request.sdkVersion | SDK 版本号 |
字段 | 类型 | 说明 |
deviceKey | String | 设备密钥,64 字符小写 hex(32 字节) |
version | int | 密钥版本号,用于密钥轮转 |
windowSize | int | 签名时间窗口大小(秒),当前固定 300 |
algorithm | String | 签名算法,当前固定 HMAC-SHA256 |
allowPersist | boolean | 是否允许 SDK 在本地持久化保存密钥; false 时仅内存持有 |
DeviceKey 并通过 callback 回传:callback.onResult(new DeviceKey(deviceKey, // 设备密钥,64 字符小写 hexversion, // 密钥版本号windowSize, // 时间窗口(秒),当前约定 300algorithm, // 签名算法,当前固定 "HMAC-SHA256"allowPersist), // 是否允许本地持久化保存errorCode, errorMessage);
回传情况 | 处理规则 |
errorCode == 0,deviceKey 非空 | 启用签名 |
errorCode == 0,deviceKey 为空或未返回 | 视为一次有效获取,本次不携带签名,且不影响已缓存的密钥 |
errorCode != 0 | 获取失败,使用上一次成功获取的密钥继续签名;无可用密钥时请求不携带签名发出,业务请求不中断 |
项 | 约定 |
密钥格式 | 64 字符小写 hex(32 字节),格式不合法将导致签名失败 |
签名算法 | HMAC-SHA256 |
时间窗口 | 当前约定 300 |
密钥版本 | 通过 version 标识,Super App as a Service 后台可据此完成密钥轮转;出现密钥版本过期时,SDK 会丢弃本地密钥并重新向宿主获取 |
密钥缓存 | 获取成功后在 SDK 侧缓存并复用; allowPersist = false 时仅在内存持有,下次启动重新向宿主获取 |
获取失败 | 回退使用已缓存密钥;无缓存时请求不携带签名发出,不影响业务可用性 |
false(或使用默认实现,默认返回 false)即不启用签名,小程序功能不受影响,仅缺少请求防篡改校验。是否强制启用取决于Super App as a Service 后台租户配置。allowPersist 应如何取值?false,密钥仅保存在内存中,进程重启后重新向宿主获取;无特殊要求时设为 true,可减少密钥接口调用次数。// Superapp 复用登录后端为 SDK 获取防篡改 DeviceKey- (void)fetchAntiTamperDeviceKeyWithParams:(NSDictionary *)paramscompletionHandler:(void(^)(NSDictionary * _Nullable result,NSError * _Nullable error))completionHandler;
字段 | 说明 |
uuid | SDK 生成并持久化的设备 UUID(36 字符) |
appId | 当前 SDK 配置的 appKey |
platform | 固定 "ios" |
sdkVersion | 当前 SDK 版本号 |
字段 | 说明 |
deviceKey | 64 字符 hex(必填;为空且无 error 时视为「本场景不启用签名」) |
version | 密钥版本号(可选) |
windowSize | 时间窗口长度(秒,可选,默认 300) |
algorithm | 固定 "HMAC-SHA256"(可选) |
- (void)fetchAntiTamperDeviceKeyWithParams:(NSDictionary *)paramscompletionHandler:(void (^)(NSDictionary * _Nullable, NSError * _Nullable))completionHandler {NSString *url = [NSString stringWithFormat:@"%@api/v1/device/key", self.serverBaseURL];NSDictionary *body = @{@"uuid": params[@"uuid"] ?: @"",@"appId": params[@"appId"] ?: @"",@"platform": params[@"platform"] ?: @"ios",@"sdkVersion": params[@"sdkVersion"] ?: @"",@"deviceAttestation": @"",};// 复用登录同一套网络封装[self.networkManager POST:url parameters:body completion:^(NSDictionary *json, NSError *error) {if (error) { completionHandler(nil, error); return; }if ([json[@"code"] integerValue] == 0 && [json[@"data"][@"deviceKey"] length] > 0) {completionHandler(json[@"data"], nil); // 透传 data(含 deviceKey/version/windowSize)} else {completionHandler(nil, [NSError errorWithDomain:@"DeviceKey"code:[json[@"code"] integerValue]userInfo:@{NSLocalizedDescriptionKey: json[@"message"] ?: @"error"}]);}}];}
项 | 说明 |
租户 ID(customId) | 租户唯一标识,形如 T04914TJ0911724TSAK,与 SDK 请求中的租户 ID 一致 |
租户密钥(TenantKey) | 由平台生成并通过安全渠道交付,64 字符小写 hex(32 字节),每个租户一份 |
密钥版本号(version) | 与 TenantKey 一一对应的正整数,首次开通为 1 |
{"deviceKey": {"tenantKeys": {"T04914TJ0911724TSAK": {"current": { "key": "<64字符小写hex>", "version": 1 },"previous": { "key": "", "version": 0, "expireAt": 0 }}}}}
字段 | 说明 |
current.key | 当前生效的 TenantKey,64 字符 hex |
current.version | 当前版本号,正整数 |
previous | 上一版本密钥,仅在密钥轮转期间保留,无则留空 |
项 | 值 |
请求方式 | POST |
路径 | /api/v1/device/key(如部署带上下文路径,则为 {context}/api/v1/device/key) |
Content-Type | application/json |
协议 | HTTPS |
鉴权 | 无需用户 Token,使用 IP 限频保护 |
参数 | 类型 | 必填 | 说明 |
uuid | String | 是 | 设备唯一标识,36 字符,格式 8-4-4-4-12,SDK 生成并持久化 |
appId | String | 是 | Super App as a Service 后台分配的应用 ID |
customId | String | 是 | 租户 ID,用于选择对应的 TenantKey |
sdkVersion | String | 否 | SDK 版本号 |
platform | String | 否 | 平台标识,android / ios |
deviceAttestation | String | 否 | 预留字段,设备证明信息,当前不使用,可忽略 |
{"uuid": "550e8400-e29b-41d4-a716-446655440000","appId": "app-hh5wgi3l1q","customId": "T04914TJ0911724TSAK","platform": "android","sdkVersion": "2.3.9","deviceAttestation": ""}
校验项 | 规则 | 失败处理 |
请求体 | 合法 JSON,必填字段齐全 | 返回参数错误 |
uuid | 长度 36,匹配 ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ | 返回参数错误 |
appId | 非空 | 返回参数错误 |
customId | 非空,且在配置中存在 | 参数缺失返回参数错误;租户未配置返回失败,不得使用其他租户的密钥代替 |
DeviceKey = HMAC-SHA256( key = TenantKey(32 字节原始值), message = "tcmpp:device:" + appId + ":" + uuid )
要点 | 说明 |
key | TenantKey 需先从 hex 解码为 32 字节,不能直接使用 hex 字符串 |
message | UTF-8 字符串,appId、uuid 使用请求中的原始值,不要转换大小写,不要去除连字符 |
输出 | 32 字节,编码为 64 字符小写 hex |
byte[] tenantKey = hexToBytes(tenantKeyHex); // 32 字节String info = "tcmpp:device:" + appId + ":" + uuid;Mac mac = Mac.getInstance("HmacSHA256");mac.init(new SecretKeySpec(tenantKey, "HmacSHA256"));String deviceKey = bytesToHexLower(mac.doFinal(info.getBytes(StandardCharsets.UTF_8)));
mac := hmac.New(sha256.New, tenantKey) // tenantKey 为 32 字节mac.Write([]byte("tcmpp:device:" + appId + ":" + uuid))deviceKey := hex.EncodeToString(mac.Sum(nil))
字段 | 类型 | 说明 |
deviceKey | String | 设备密钥,64 字符小写 hex(32 字节) |
version | int | 密钥版本号,即本次派生所用 TenantKey 的版本,用于密钥轮转 |
windowSize | int | 签名时间窗口大小(秒),当前固定 300 |
algorithm | String | 签名算法,当前固定 HMAC-SHA256 |
allowPersist | boolean | 可选,是否允许 SDK 在本地持久化保存密钥;false 时仅内存持有。不返回时默认 true |
{"returnCode": "0","returnMessage": "OK","requestId": "e1d137d70b0e4433ba068c4c2c4ee1da","data": {"deviceKey": "b8bab3bf5232930a01695f894f5f85848ba0048a172bd3b168c6ec0dbd6ac399","version": 1,"windowSize": 300,"algorithm": "HMAC-SHA256"}}
{"returnCode": "400001","returnMessage": "Invalid parameter","requestId": "a17888625dd34fcba59a6ad790d45c0d","data": null}
字段 | 类型 | 说明 |
returnCode | String | "0" 表示成功,其他值表示失败 |
returnMessage | String | 结果描述 |
requestId | String | 请求追踪 ID,便于排查问题 |
data | Object | 成功时为上表字段,失败时为 null |
returnCode | 含义 | 宿主 / SDK 处理 |
0 | 成功 | 回传密钥,SDK 缓存使用 |
400001 | 参数错误 | 回传失败,SDK 使用已缓存密钥继续 |
500001 | 系统错误(含租户未配置) | 回传失败,SDK 使用已缓存密钥继续 |
429 | 触发限频 | 回传失败,SDK 使用已缓存密钥继续 |
项 | 建议 |
维度 | 客户端 IP |
窗口 | 1 小时 |
阈值 | 参考 180000 次/IP/小时,请按自身业务规模调整 |
超限响应 | 429 |
限频存储故障 | 放行请求,不能因限频组件故障导致接口整体不可用 |
项 | 约定 |
密钥格式 | deviceKey 为 64 字符小写 hex(32 字节),格式不合法将导致签名失败 |
签名算法 | HMAC-SHA256 |
时间窗口 | 当前约定 300 秒 |
租户隔离 | 按 customId 区分 TenantKey,未配置的租户直接返回失败,不得回退到其他租户 |
版本一致 | 返回的 version 必须与平台侧在网关登记的版本一致,且 DeviceKey 必须由该版本对应的 TenantKey 派生,否则网关返回 1075 |
密钥保密 | TenantKey 不得下发给客户端,也不得写入代码仓库;日志中禁止打印 TenantKey 和 DeviceKey,排查时只记录 customId、appId、uuid、version |
传输安全 | 接口必须使用 HTTPS,响应中 DeviceKey 为明文 |
重复调用 | 密钥轮转或客户端缓存丢失时接口会被再次调用,实现需支持重复调用且结果幂等(相同入参返回相同密钥) |
服务可用 | 接口异常不影响业务请求,SDK 会回退到已缓存密钥或不携带签名发送请求 |
错误码 | 含义 | 处理建议 |
1070 | 签名头缺失或格式错误 | 频繁出现时排查密钥下发与签名配置 |
1071 | 签名不匹配(请求内容被篡改或密钥错误) | 频繁出现时排查密钥下发与签名配置 |
1072 | 时间戳超出允许偏移(偏移 > 600s) | 检查设备系统时间 |
1073 | 随机数重复(重放请求) | 正常情况下不应出现 |
1074 | 租户未注册 | 联系 Super App as a Service 后台确认租户配置 |
1075 | 密钥版本过期 | SDK 自动重新获取密钥,无需宿主处理 |
1076 | 设备已吊销 | Super App as a Service 后台侧设备管理策略,联系后台确认 |
文档反馈