tencent cloud

腾讯云超级应用服务

文档腾讯云超级应用服务实践教程SDK 网络请求防篡改实践教程

SDK 网络请求防篡改实践教程

下载
聚焦模式
字号
最后更新时间: 2026-11-17 16:39:12
防篡改签名用于对 SDK 发起的网络请求进行完整性校验:SDK 基于 superapp 提供的设备密钥(DeviceKey)对请求计算 HMAC-SHA256 签名并附加到请求中,Super App as a Service 后台侧完成验签,从而识别请求参数篡改与重放。

整体流程



接入指引

Android

接入步骤

1.实现设备密钥获取接口

在宿主的 MiniAppProxy 实现类中覆写 getDeviceKey(实现类通常继承 BaseMiniAppProxyImpl,并通过 @ProxyService 注解注册):
@Override
public boolean getDeviceKey(DeviceKeyRequest request, DeviceKeyCallback callback) {
// 由 superapp 自行实现:向自有后台请求设备密钥,并通过 callback 回传
}
返回值语义
返回值
含义
后续行为
true
当前宿主启用签名能力,由宿主代理设备密钥的获取
SDK 等待 callback 的回调结果;密钥到位后请求携带签名
false
当前宿主不启用签名能力
SDK 丢弃 callback,请求不携带签名,后续不再回调该接口
实现要求
返回 true 时,必须在所有分支(成功、后台返回失败、本地异常)最终回调 callback 一次;若长时间未回调,SDK 将按本次获取失败处理,请求不中断。
网络请求须在宿主侧异步执行后回调,不得在本方法内同步等待网络返回。
回调可在任意线程执行。
该接口可能被多次调用(密钥轮转场景),实现需支持重复调用。

2.向自有后台请求设备密钥

接口地址、协议、鉴权方式由 superapp 自行定义,SDK 不做约束。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 时仅内存持有

3.回传结果

将后台响应封装为 DeviceKey 并通过 callback 回传:
callback.onResult(new DeviceKey(
deviceKey, // 设备密钥,64 字符小写 hex
version, // 密钥版本号
windowSize, // 时间窗口(秒),当前约定 300
algorithm, // 签名算法,当前固定 "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 时仅在内存持有,下次启动重新向宿主获取
获取失败
回退使用已缓存密钥;无缓存时请求不携带签名发出,不影响业务可用性

常见问题

Q1:不接入是否影响小程序功能?
返回 false(或使用默认实现,默认返回 false)即不启用签名,小程序功能不受影响,仅缺少请求防篡改校验。是否强制启用取决于Super App as a Service 后台租户配置。
Q2:密钥获取接口的调用频率如何?
密钥获取成功后会在 SDK 侧缓存复用,通常每个租户 + 应用维度在进程内仅获取一次;仅在密钥轮转(Super App as a Service 后台返回 1075)或不允许持久化(进程重启)时重新获取。
Q3:allowPersist 应如何取值?
对密钥落盘有安全合规要求的应用可设为 false,密钥仅保存在内存中,进程重启后重新向宿主获取;无特殊要求时设为 true,可减少密钥接口调用次数。
Q4:密钥接口请求失败时是否需要宿主重试?
不需要。宿主回传失败错误码即可,SDK 使用已缓存密钥继续处理;无缓存时请求不携带签名发出。
Q5:是否需要区分主进程与小程序进程?
不需要。密钥获取统一在主进程完成,宿主实现无需关注进程差异。

iOS

前提条件

实现签名验证,需要创建一个类并遵循 TMFMiniAppSDKDelegate 协议,并将其注册为 SDK 的代理,具体配置可以参考介绍。SAS 需要已开通签名验证能力(网关侧验签),superapp 后端能够下发 DeviceKey。

接入步骤

在遵循 TMFMiniAppSDKDelegate 协议的代理类中实现以下可选方法:
// Superapp 复用登录后端为 SDK 获取防篡改 DeviceKey
- (void)fetchAntiTamperDeviceKeyWithParams:(NSDictionary *)params
completionHandler:(void(^)(NSDictionary * _Nullable result,
NSError * _Nullable error))completionHandler;
SDK 在首次请求或 DeviceKey 过期(网关返回 1075)时会回调该方法,由 superapp 负责获取 DeviceKey 并回传。
SDK 传入的 params:
字段
说明
uuid
SDK 生成并持久化的设备 UUID(36 字符)
appId
当前 SDK 配置的 appKey
platform
固定 "ios"
sdkVersion
当前 SDK 版本号
superapp 复用其登录的同一套后端服务,请求获取 DeviceKey 后按约定格式回传,字段如下:
字段
说明
deviceKey
64 字符 hex(必填;为空且无 error 时视为「本场景不启用签名」)
version
密钥版本号(可选)
windowSize
时间窗口长度(秒,可选,默认 300)
algorithm
固定 "HMAC-SHA256"(可选)

接入示例

- (void)fetchAntiTamperDeviceKeyWithParams:(NSDictionary *)params
completionHandler:(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"}]);
}
}];
}

注意事项

回调超时:completionHandler 需在 15 秒内回调,否则 SDK 按失败处理,避免请求链挂起。
签名范围:仅 POST / PUT 请求会被签名,GET / DELETE 不需要(网关直接放行)。
降级策略:返回空 deviceKey(无 error)或未实现本代理 → 判定本场景不启用签名,后续请求不再反复回调宿主。
线程安全:回调线程不保证为主线程,处理时请注意线程安全。

后台

接入前准备

接入前请联系 Super App as a Service 平台侧,获取以下信息:
项
说明
租户 ID(customId)
租户唯一标识,形如 T04914TJ0911724TSAK,与 SDK 请求中的租户 ID 一致
租户密钥(TenantKey)
由平台生成并通过安全渠道交付,64 字符小写 hex(32 字节),每个租户一份
密钥版本号(version)
与 TenantKey 一一对应的正整数,首次开通为 1

接入步骤

1.配置租户密钥

Superapp 需要按租户保存 TenantKey 和版本号。多租户场景下,不同 customId 必须使用各自的 TenantKey,不允许共用。
配置示例(格式可按自身框架调整,只需满足按租户区分并保存版本号):
{
"deviceKey": {
"tenantKeys": {
"T04914TJ0911724TSAK": {
"current": { "key": "<64字符小写hex>", "version": 1 },
"previous": { "key": "", "version": 0, "expireAt": 0 }
}
}
}
}
字段
说明
current.key
当前生效的 TenantKey,64 字符 hex
current.version
当前版本号,正整数
previous
上一版本密钥,仅在密钥轮转期间保留,无则留空
启动时需要校验:至少配置一个租户;TenantKey 是合法 hex 且解码后为 32 字节;版本号为正整数。校验不通过应当让服务启动失败,不要在密钥未就绪的状态下对外提供接口。

2.实现设备密钥下发接口

接口地址、鉴权方式由 superapp 自行定义,SDK 不做约束。推荐如下定义:
项
值
请求方式
POST
路径
/api/v1/device/key(如部署带上下文路径,则为 {context}/api/v1/device/key)
Content-Type
application/json
协议
HTTPS
鉴权
无需用户 Token,使用 IP 限频保护
宿主会将 SDK 提供的参数组装为请求 Body:
参数
类型
必填
说明
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
非空,且在配置中存在
参数缺失返回参数错误;租户未配置返回失败,不得使用其他租户的密钥代替

3.派生设备密钥

用 customId 找到对应租户的当前 TenantKey,按如下方式派生 DeviceKey:
DeviceKey = HMAC-SHA256( key = TenantKey(32 字节原始值), message = "tcmpp:device:" + appId + ":" + uuid )
要点
说明
key
TenantKey 需先从 hex 解码为 32 字节,不能直接使用 hex 字符串
message
UTF-8 字符串,appId、uuid 使用请求中的原始值,不要转换大小写,不要去除连字符
输出
32 字节,编码为 64 字符小写 hex
uuid 的大小写必须与 SDK 发给网关的 TC-Uuid 完全一致,否则网关验签失败(错误码 1071)
参考实现(Java):
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)));
参考实现(Go):
mac := hmac.New(sha256.New, tenantKey) // tenantKey 为 32 字节
mac.Write([]byte("tcmpp:device:" + appId + ":" + uuid))
deviceKey := hex.EncodeToString(mac.Sum(nil))

4.返回结果

后台响应需包含以下字段:
字段
类型
说明
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 是否为 "0" 判断成功,并读取 data。建议错误码如下,数值可自行定义:
returnCode
含义
宿主 / SDK 处理
0
成功
回传密钥,SDK 缓存使用
400001
参数错误
回传失败,SDK 使用已缓存密钥继续
500001
系统错误(含租户未配置)
回传失败,SDK 使用已缓存密钥继续
429
触发限频
回传失败,SDK 使用已缓存密钥继续

5.接口限频

项
建议
维度
客户端 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 会回退到已缓存密钥或不携带签名发送请求

常见问题

Q1:后台不实现该接口是否影响小程序功能?
未启用签名能力时不影响,小程序功能正常,仅缺少请求防篡改校验。但如果平台侧已为租户开启强制校验,且 SDK 版本达到要求,没有获取到密钥的请求会被网关拒绝(错误码 1070)。请先完成后台接口并联调通过,再联系平台开启强制校验。
Q2:设备密钥接口的调用频率如何?
密钥获取成功后会在 SDK 侧缓存复用,通常每个租户 + 应用维度在进程内获取一次。仅在密钥轮转(网关返回 1075)或不允许持久化(进程重启)时重新获取,因此接口压力很小。
Q3:allowPersist 应如何取值?
对密钥落盘有安全合规要求的应用可设为 false,密钥仅保存在内存,进程重启后重新向后台获取。无特殊要求时不返回或设为 true,可减少接口调用次数。
Q4:多个租户是否可以共用一个 TenantKey?
不可以。每个租户的 TenantKey 由平台独立生成,网关按租户校验。共用会导致其他租户的签名验证失败。
Q5:接口请求失败时,SDK 会怎么处理?
SDK 使用已缓存的密钥继续签名;没有缓存时,请求不携带签名发出,业务请求不中断。
Q6:网关返回 1071(签名不匹配)应如何排查?
依次检查:TenantKey 是否与平台交付的一致;appId、uuid 是否使用原始值(含大小写)派生;派生时是否将 TenantKey 先 hex 解码为 32 字节;用上文自测用例确认派生函数结果一致。
Q7:网关返回 1075(密钥版本过期)应如何排查?
通常是返回的 version 与网关登记的版本不一致。请与平台确认网关侧当前版本,并核对 superapp 配置的版本号与密钥是否对应。
Q8:接口返回系统错误,提示租户密钥未配置?
检查 customId 是否在租户配置中存在,以及配置里租户 ID 的大小写比较规则。如果使用的配置框架会改变 key 大小写,需要在存储和查找时统一处理。另外请检查配置 JSON 括号是否配对,多个租户节点需同级并列,不要嵌套在上一个租户内部。
Q9:是否需要实现 GET /api/v1/tenant/version 查询接口?
不需要。该接口仅用于运维查看租户密钥版本,SDK 和网关都不依赖它。如需实现,必须鉴权并限制内网访问。

错误码

Super App as a Service 后台接入层返回的签名相关错误码。
错误码
含义
处理建议
1070
签名头缺失或格式错误
频繁出现时排查密钥下发与签名配置
1071
签名不匹配(请求内容被篡改或密钥错误)
频繁出现时排查密钥下发与签名配置
1072
时间戳超出允许偏移(偏移 > 600s)
检查设备系统时间
1073
随机数重复(重放请求)
正常情况下不应出现
1074
租户未注册
联系 Super App as a Service 后台确认租户配置
1075
密钥版本过期
SDK 自动重新获取密钥,无需宿主处理
1076
设备已吊销
Super App as a Service 后台侧设备管理策略,联系后台确认


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈