Security HTTP 第三方移动 SDK 权限与系统能力申请指南

版本：v1.0 适用范围：客户/合作方开发者集成 Security HTTP 第三方 Android AAR 或 iOS XCFramework 覆盖平台：Android、iOS 阅读对象：客户 App 的产品、Android/iOS 开发、发布和隐私合规人员重要说明：本文只描述客户第三方 SDK 接入要求，不包含项目内部 App 的接入流程

1. 先看结论

Security HTTP SDK 是 VPN/安全网络加速 SDK，不是普通网络请求 SDK。客户 App 需要为“创建系统 VPN、运行隧道、与扩展或服务共享配置”准备平台能力，但不需要申请通讯录、定位、蓝牙、相机、麦克风或短信权限。

第三方 App 使用客户自己的 Backend 申请一次性 Bootstrap Token；app_secret 只能保存在客户 Backend，不能放进 APK、IPA、XCConfig、Info.plist、远程配置或日志。这里三个字段的边界是：app_key 是可公开的应用标识，可以配置在移动端；app_secret 是客户 Backend 调用控制面的机密凭据；Bootstrap Token 是客户 Backend 临时申请、再交给移动端 SDK 兑换短期 SDK Access Token 的一次性凭据。

平台	必须准备	用户/系统授权方式
iOS	Packet Tunnel Extension、Network Extensions capability、Packet Tunnel entitlement、App Groups、两套签名配置	首次保存/启动 VPN 配置时由系统展示 VPN 授权；不是普通 Info.plist 运行时权限
Android	`VpnService`、前台服务、网络权限、前台服务通知能力	首次连接调用 `VpnService.prepare()`，Android 13+ 另需运行时申请通知权限

2. 客户需要向哪里申请

以下入口均为平台官方入口。客户应使用自己的 Apple Developer Team、Google Play 开发者账号和应用标识，不要使用 SDK 提供方的账号或示例工程标识。

平台	申请/配置事项	官方入口
iOS	加入 Apple Developer Program	Apple Developer Program
iOS	创建主 App 与 Packet Tunnel Extension 的 Explicit App ID，并启用能力	Register an App ID
iOS	启用 Network Extensions、App Groups 等 App ID 能力	Enable app capabilities
iOS	配置 Network Extension 与 Packet Tunnel	Configuring network extensions
iOS	生成开发/发布证书、两个 Bundle ID 对应的 provisioning profile	Certificates, Identifiers & Profiles
iOS	创建、配置和提交 TestFlight/App Store 版本	App Store Connect
Android	Google Play 上架（仅选择 Google Play 分发时需要）	Google Play Console
Android	Android SDK、Manifest、VpnService 开发规范	Android VPN developer guide
Android	Android 13+ 通知运行时权限	Notification runtime permission
Android	Android 14+ 前台服务类型	Foreground service types
Android	Google Play 上架时检查权限、数据安全和审核声明（非 Google Play 分发无需此账号）	Play Console policy resources

Apple Developer 能力配置和 Android 系统权限是 SDK 正常运行所需的技术准备；Google Play 开发者账号只在客户选择 Google Play 分发时需要。客户也可以通过企业签名、企业应用商店、MDM、官网下载、私有设备管理或其他合规 Android 分发渠道交付 App，但仍必须遵守 Android 系统对 VPN、前台服务和通知的运行规则，以及客户所选分发渠道的审核/合规要求。

这些链接是申请和配置入口，不代表 Apple 或 Google 一定批准相关能力。Google Play 的审核政策只约束 Google Play 分发；不通过 Google Play 分发并不意味着可以绕过 Android 系统权限、用户 VPN 授权、隐私告知或当地法律要求。

1.1 当前 SDK 版本基线

以本项目当前交付基线为准：iOS XCFramework 最低部署版本为 iOS 13.0；Android AAR 最低运行 API 为 23，消费工程应使用 compile SDK 34 或更高版本。客户拿到新版本 SDK 后，应以随包 README、变更说明和实际 Manifest 为最终依据，并重新检查本文矩阵。

2. 权限分级规则

2.1 SDK 必需项

缺少这些配置，SDK 无法建立系统隧道或无法稳定运行：

iOS：主 App 与 Packet Tunnel Extension 的 Network Extension / Packet Tunnel 配置、App Group、正确的 Bundle ID 与签名 profile。
Android：INTERNET、ACCESS_NETWORK_STATE、FOREGROUND_SERVICE、SDK 的 VpnService 声明，以及用户同意的 VPN 授权。

2.2 按版本或功能启用

Android 13（API 33）及以上：POST_NOTIFICATIONS，用于显示 VPN 前台服务通知；必须由客户 App 的 Activity 在运行时申请。拒绝通知权限不会自动等同于拒绝 VPN 授权，但通知栏可能不可见。
Android 14（API 34）及以上：前台服务类型和对应声明必须与 SDK AAR 合并结果一致。当前 SDK 使用 specialUse，并声明 FOREGROUND_SERVICE_SPECIAL_USE。
Android 按应用加速/应用目录能力：可能需要包可见性配置；仅在宿主确实要枚举其他 App 时启用，不属于 VPN 建链的通用权限。

2.3 不应随 SDK 默认申请

当前 SDK 代码和交付物未要求以下权限：定位、通讯录、电话、短信、相机、麦克风、蓝牙、日历、精确闹钟、外部存储读写、悬浮窗、开机自启、无障碍服务、设备管理员、QUERY_ALL_PACKAGES、REQUEST_INSTALL_PACKAGES。

若客户 App 的其他业务功能另有需要，必须由客户单独说明用途、按系统规则申请，并在隐私政策和商店申报中单独披露；不能以“接入 SDK 需要”为理由一起申请。

3. iOS 接入要求

3.1 Target 结构

宿主工程必须包含两个 Target：

主 App Target。
Network Extension > Packet Tunnel Target。

示例标识符：

text

主 App：com.partner.mobile
Extension：com.partner.mobile.PacketTunnel
App Group：group.com.partner.mobile

第三方 XCFramework 应同时链接到主 App 和 Extension，当前交付为静态 framework：两个 Target 均使用 Do Not Embed；Extension 需要 $(inherited) -all_load，否则 Provider 入口可能被链接器裁剪。

3.2 Apple Developer 与 Xcode 能力

Apple Developer 后台、Xcode Target 和 provisioning profile 必须保持一致：

配置项	主 App	Packet Tunnel Extension	说明
Network Extensions capability	是	是	选择 Packet Tunnel
`packet-tunnel-provider` entitlement	是	是	当前 SDK 的隧道类型
App Groups capability	是	是	必须使用同一个 Group ID
Bundle ID	主 App ID	独立 Extension ID	Extension ID 必须传给 SDK
Provisioning profile	独立 profile	独立 profile	同一 Team、设备和能力

两个 Target 的关键 entitlements：

xml

<key>com.apple.developer.networking.networkextension</key>
<array>
    <string>packet-tunnel-provider</string>
</array>
<key>com.apple.security.application-groups</key>
<array>
    <string>group.com.partner.mobile</string>
</array>

若 SDK 版本要求通过 Keychain 在主 App 与 Extension 间共享安装实例私钥，还要在两个 Target 配置一致的 keychain-access-groups，例如：

xml

<key>keychain-access-groups</key>
<array>
    <string>$(AppIdentifierPrefix)com.partner.mobile.sechttp</string>
</array>

具体 Access Group 必须以当前交付包的接入参数和最终签名 Team 为准，不能直接复制示例工程的值。

3.3 Extension Info.plist

Packet Tunnel Extension 必须声明：

xml

<key>NSExtension</key>
<dict>
    <key>NSExtensionPointIdentifier</key>
    <string>com.apple.networkextension.packet-tunnel</string>
    <key>NSExtensionPrincipalClass</key>
    <string>SecHttp.PacketTunnelProvider</string>
</dict>

主 App 构建产物还必须在 Embed App Extensions 中包含对应 .appex。

3.4 iOS 用户授权与说明

iOS 没有 Android 式的 uses-permission 清单。宿主 App 调用 SDK 创建/保存 VPN 配置后，系统可能显示“允许添加 VPN 配置”的系统确认；宿主必须正确处理用户拒绝、系统设置中关闭 VPN、配置保存失败和设备离线。

当前项目工程使用了：

xml

<key>NSVPNUsageDescription</key>
<string>Allow this app to create secure VPN sessions for global acceleration.</string>

该字段应与当前 SDK/系统版本及商店审核要求一起确认，文案要说明 VPN 的用途、流量处理范围和用户可关闭方式。不要把它当作替代 Network Extension entitlement 的权限声明。

不需要为当前 SDK 增加定位、通讯录、相机、麦克风或蓝牙 Usage Description。

3.5 iOS 发布前检查

主 App 与 Extension 使用同一 Apple Team，但 Bundle ID、profile 和证书配置正确分离。
两个 Target 的 App Group 逐字一致；不要沿用示例工程或旧环境的 Group ID。
最终签名产物包含 packet-tunnel-provider 和预期 App Group：

bash

codesign -d --entitlements :- PartnerApp.app
codesign -d --entitlements :- PartnerApp.app/PlugIns/PartnerPacketTunnel.appex

模拟器只能证明编译/链接及部分 API；VPN 授权、Packet Tunnel 生命周期、真实路由、DNS、切网和断网重连必须用签名真机验收。

4. Android 接入要求

4.1 SDK 当前 Manifest 权限

当前 security_http/sdk/android/src/main/AndroidManifest.xml 声明：

xml

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

这些权限会在 Gradle Manifest Merger 中合并到宿主 App。宿主应检查最终 APK/AAB，而不是只看 AAR 文件。

权限	类型	用途	宿主动作
`INTERNET`	普通权限	连接 Control API、节点和数据面	无需运行时弹窗
`ACCESS_NETWORK_STATE`	普通权限	判断物理网络、切网和重连状态	无需运行时弹窗
`FOREGROUND_SERVICE`	普通权限	让 VPN 服务以前台服务运行	声明并保持通知
`FOREGROUND_SERVICE_SPECIAL_USE`	普通权限	Android 14+ 的 `specialUse` 前台服务类型	检查 compile/target SDK 与商店申报
`POST_NOTIFICATIONS`	运行时权限（Android 13+）	显示连接状态和前台服务通知	由宿主 Activity 请求

4.2 VpnService 声明

最终 Manifest 中必须存在 SDK 的 VPN Service，结构等价于：

xml

<service
    android:name="com.securityhttp.sdk.SecHttpVpnService"
    android:exported="false"
    android:foregroundServiceType="specialUse"
    android:permission="android.permission.BIND_VPN_SERVICE">
    <intent-filter>
        <action android:name="android.net.VpnService" />
    </intent-filter>
</service>

不要把 Service 改成可被其他应用导出的组件，也不要删除 BIND_VPN_SERVICE 或 android.net.VpnService intent-filter。

4.3 Android 用户授权流程

连接前由宿主调用：

kotlin

val prepareIntent = VpnService.prepare(context)
if (prepareIntent != null) {
    startActivityForResult(prepareIntent, VPN_PERMISSION_REQUEST_CODE)
} else {
    // 已获得系统 VPN 授权，可调用 SDK 连接
}

用户拒绝时不得假设 VPN 已建立；用户在系统设置中撤销授权后，宿主需要重新走状态检查和授权流程。

Android 13+ 的通知权限由宿主 Activity 在用户主动开启 VPN 前请求：

kotlin

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    requestPermissions(arrayOf(Manifest.permission.POST_NOTIFICATIONS), NOTIFICATION_REQUEST_CODE)
}

通知权限被拒绝不等于用户拒绝 VPN，但可能导致连接状态通知不可见。产品应向用户解释通知用于显示安全连接状态；SDK 不能替代宿主展示权限说明。

4.4 Android 按应用加速的额外边界

VpnService.Builder.addAllowedApplication(packageName) 属于流量范围配置，不是新的危险权限。若宿主 App 要读取设备上其他应用的包名，才需要处理 Android 包可见性规则：

优先使用 <queries> 声明确实需要查询的包、Intent 或 Provider。
只有业务确实需要广泛枚举所有安装应用时，才评估 QUERY_ALL_PACKAGES；它不是 SDK 建链必需项，Google Play 对其用途有严格限制。
REQUEST_INSTALL_PACKAGES、外部存储读写、SYSTEM_ALERT_WINDOW 不属于当前 SDK 的按应用加速要求；仅在宿主自身有安装包分发、导入文件或悬浮窗功能时单独申请。

4.5 Android 构建与分发检查

检查最终 Manifest 是否包含 SDK Service、BIND_VPN_SERVICE、specialUse 与所需权限。
Android 13 真机验证通知运行时授权、拒绝后的连接表现和通知渠道。
Android 14 真机验证前台服务启动限制、通知、切网、后台运行和用户停止服务。
Android 设备验证 VpnService.prepare()、连接、切换节点、断开、系统设置撤销授权后的恢复。
无论是否上架 Google Play，都要检查最终 APK/AAB 的 Manifest，删除客户业务不需要的 QUERY_ALL_PACKAGES、REQUEST_INSTALL_PACKAGES、存储或悬浮窗权限。
如果选择 Google Play 分发，再额外完成 Play Console 的权限声明、数据安全表单、VPN/前台服务审核说明和其他商店材料；Google Play 账号不是 SDK 运行的前置条件。
如果选择企业签名、MDM、企业商店、官网下载或其他分发渠道，则按该渠道的签名、安装、设备管理和更新规则交付，不需要为了接入 SDK 额外注册 Google Play 账号。

5. 客户开发者的接入职责

客户开发团队需要完成以下工作，SDK 提供方不代替客户申请客户自己的开发者能力、证书、Bundle ID 或包名。商店账号不是 SDK 接入的统一前置条件，只有客户选择对应商店分发时才需要注册和提交商店材料：

在 Apple Developer 后台创建客户自己的 App ID；Android 侧创建客户自己的 package name 和签名体系。只有选择 Google Play 分发时，才需要使用 Google Play Console。
按本文配置 iOS 主 App、Packet Tunnel Extension 或 Android VpnService。
在客户 Backend 安全保存 app_secret，并实现 SDK 所需的一次性 Bootstrap Token 下发。
在客户 App 中展示清晰的 VPN/通知授权前说明，并处理用户允许、拒绝、撤销和系统异常。
在隐私政策中如实说明 VPN 的用途、流量处理范围和通知用途；如果选择应用商店分发，再填写对应商店的数据安全表单和审核备注。
使用客户自己的签名证书和发布包进行真机联调；不能用 SDK 示例包或 SDK 提供方签名包替代验收。

5.1 三类凭据的正确流转

text

客户 Backend --(app_key + app_secret)--> Security HTTP Control API
客户 Backend <--(bootstrap_token)------- Security HTTP Control API
客户 Backend --(bootstrap_token)--------> 客户 App
客户 App    --(bootstrap_token + 安装实例签名)--> Security HTTP Control API
客户 App    <--(短期 SDK Access Token)---------- Security HTTP Control API

凭据	放置位置	是否进入 APK/IPA	说明
`app_key`	客户 App 配置、客户 Backend	可以	公开应用标识，不单独授予代理权限
`app_secret`	客户 Backend 的密钥管理系统/服务端环境	不可以	用于客户 Backend 认证创建 Bootstrap Token；创建或轮换时通常只显示一次
`bootstrap_token`	客户 Backend 临时缓存、客户 App 内存/SDK	可以临时传递	默认短时有效且单次消费，不应写日志、持久化或提交到崩溃/埋点系统
SDK Access Token	SDK 内部短期使用	不应由业务层持久化	用于 SDK 后续控制面/数据面请求，具体由 SDK 版本管理

因此，原句是正确的，但更完整、面向客户开发者的推荐写法是：

客户 App 不直接持有 app_secret。客户 Backend 使用 app_key + app_secret 向 Security HTTP 控制面申请一次性 Bootstrap Token，再将该 Token 临时交给客户 App 传入第三方 SDK。app_key 可以放入 APK/IPA；app_secret 只能保存在客户 Backend 的服务端密钥管理环境中，禁止写入 APK、IPA、XCConfig、Info.plist、远程配置、日志、崩溃报告或埋点数据。

5.2 推荐的用户提示用语

VPN 授权前，客户可以根据实际业务调整以下文案：

text

开启安全网络连接后，应用会通过系统 VPN 通道转发本应用选择的网络流量，
用于建立加密连接并访问安全加速服务。连接期间系统会显示 VPN 状态，
你可以随时在应用内或系统设置中断开。

Android 通知授权前：

text

允许通知后，应用才能在安全连接运行期间显示连接中、已连接、重连和异常状态。
该通知用于展示连接状态，不用于广告推送。

iOS NSVPNUsageDescription 建议使用与真实产品一致的中英文文案，例如：

text

中文：允许应用创建安全 VPN 连接，用于加密和加速应用网络流量。你可以随时断开连接。
English: Allow this app to create a secure VPN connection to encrypt and accelerate app traffic. You can disconnect at any time.

不要使用“获取所有网络数据”“监控用户上网行为”等超出实际用途或容易引起误解的表述。若产品实际转发全部设备流量，必须按真实行为修改文案、隐私政策和商店审核材料。

5.3 提交审核时可使用的技术说明

客户可将以下事实按实际产品情况改写后放入审核备注，不应原样提交与实际行为不符的内容：

text

本应用集成 Security HTTP 第三方移动 SDK。SDK 使用 iOS Packet Tunnel Provider /
Android VpnService 建立用户主动开启的安全网络连接。VPN 用于加密并转发应用定义范围内
的网络流量至合作方安全节点。用户可以在应用内停止连接，也可以在系统 VPN 设置中撤销授权。
Android 前台服务通知仅用于展示 VPN 连接状态和重连状态。SDK 不需要通讯录、定位、相机、
麦克风、蓝牙或短信权限。长期 app_secret 仅保存在客户服务端，不写入移动端。

客户必须根据实际是“全局 VPN”还是“按应用/按目标范围 VPN”、是否记录连接日志、是否处理 IP/流量统计等情况补充和修正。

6. 宿主 App 交付清单

iOS

[ ] 主 App 和 Packet Tunnel Extension 两个 Target 已创建。
[ ] 两个 Target 均启用 Network Extensions / Packet Tunnel。
[ ] 两个 Target 均启用同一个 App Group。
[ ] 两个 Target 的 Bundle ID、Team、profile、证书和 Extension ID 已对齐。
[ ] Extension Info.plist 配置正确的 NSExtensionPointIdentifier 和 Provider 类。
[ ] XCFramework 同时链接到两个 Target，静态库使用 Do Not Embed，Extension 配置 -all_load。
[ ] 已处理系统 VPN 授权、拒绝、撤销、切网和断网重连。
[ ] 已在签名真机验证，而不是只依据模拟器或编译成功。

Android（与分发渠道无关）

[ ] AAR 已正确合并 INTERNET、ACCESS_NETWORK_STATE、前台服务和通知声明。
[ ] SDK VpnService 未被 Manifest Merger 删除或导出。
[ ] 连接前已处理 VpnService.prepare()。
[ ] Android 13+ 已由宿主 Activity 请求 POST_NOTIFICATIONS。
[ ] Android 14+ 已验证 specialUse 前台服务声明；若选择 Google Play，再完成对应商店申报。
[ ] 若实现按应用列表，已按实际范围配置 <queries>；没有无理由加入 QUERY_ALL_PACKAGES。
[ ] 未把安装包、存储、悬浮窗等宿主业务权限误写入 SDK 接入清单。
[ ] 已在目标 Android 版本真机验证连接、通知、后台、切网、断开和撤销授权。

仅在选择 Google Play 分发时

[ ] 已注册并配置客户自己的 Google Play Console 应用。
[ ] 已完成 Google Play 要求的 VPN、前台服务、权限和数据安全声明。
[ ] 已确认提交包中的权限与审核描述、隐私政策和实际行为一致。

选择其他 Android 分发渠道时

[ ] 已确认该渠道支持客户使用的签名、APK/AAB 格式和更新机制。
[ ] 已向客户设备管理员/企业商店说明 VPN 用户授权、通知和后台运行要求。
[ ] 已按实际分发渠道准备隐私政策、安装说明、签名证书和升级方案；不需要注册 Google Play 账号。

7. 验收证据边界

代码检查、Manifest/entitlement 检查、编译和单元测试只能证明静态配置或代码路径正确，不能证明系统授权和真实 VPN 流量已经可用。正式接入至少应分别记录：

静态证据：最终 Manifest、最终 entitlements、签名身份、构建产物和 SDK 版本。
用户授权证据：首次 VPN 授权、通知授权、拒绝/撤销后的状态。
运行证据：真机上的 Packet Tunnel/VpnService 启动、节点握手、真实流量、切网、重连和断开。
发布证据：目标商店对 VPN、前台服务、包可见性、隐私政策和数据用途的审核材料。

出现“编译通过但连接失败”时，优先检查签名能力、系统授权、Service/Extension 声明、App Group、Bundle ID 和真实设备日志，不要把编译成功当作权限申请完成。

8. 维护规则

当 SDK 新增系统能力时，必须同时更新：

AAR Manifest 或 iOS 接入工程模板。
本文权限矩阵和宿主交付清单。
第三方 Android/iOS 接入指南。
AndroidManifest merger 与最终 IPA/AAB 的静态检查。
真机验收和商店审核说明。

权限应按“SDK 必需、功能可选、宿主业务自有”三类维护，禁止把某个示例工程的全部权限复制到所有合作方 App。

Security HTTP 第三方移动 SDK 权限与系统能力申请指南 ​

1. 先看结论 ​

2. 客户需要向哪里申请 ​

1.1 当前 SDK 版本基线 ​

2. 权限分级规则 ​

2.1 SDK 必需项 ​

2.2 按版本或功能启用 ​

2.3 不应随 SDK 默认申请 ​

3. iOS 接入要求 ​

3.1 Target 结构 ​

3.2 Apple Developer 与 Xcode 能力 ​

3.3 Extension Info.plist ​

3.4 iOS 用户授权与说明 ​

3.5 iOS 发布前检查 ​

4. Android 接入要求 ​

4.1 SDK 当前 Manifest 权限 ​

4.2 VpnService 声明 ​

4.3 Android 用户授权流程 ​

4.4 Android 按应用加速的额外边界 ​

4.5 Android 构建与分发检查 ​

5. 客户开发者的接入职责 ​

5.1 三类凭据的正确流转 ​

5.2 推荐的用户提示用语 ​

5.3 提交审核时可使用的技术说明 ​

6. 宿主 App 交付清单 ​

iOS ​

Android（与分发渠道无关） ​

仅在选择 Google Play 分发时 ​

选择其他 Android 分发渠道时 ​

7. 验收证据边界 ​

8. 维护规则 ​

Security HTTP 第三方移动 SDK 权限与系统能力申请指南

1. 先看结论

2. 客户需要向哪里申请

1.1 当前 SDK 版本基线

2. 权限分级规则

2.1 SDK 必需项

2.2 按版本或功能启用

2.3 不应随 SDK 默认申请

3. iOS 接入要求

3.1 Target 结构

3.2 Apple Developer 与 Xcode 能力

3.3 Extension Info.plist

3.4 iOS 用户授权与说明

3.5 iOS 发布前检查

4. Android 接入要求

4.1 SDK 当前 Manifest 权限

4.2 VpnService 声明

4.3 Android 用户授权流程

4.4 Android 按应用加速的额外边界

4.5 Android 构建与分发检查

5. 客户开发者的接入职责

5.1 三类凭据的正确流转

5.2 推荐的用户提示用语

5.3 提交审核时可使用的技术说明

6. 宿主 App 交付清单

iOS

Android（与分发渠道无关）

仅在选择 Google Play 分发时

选择其他 Android 分发渠道时

7. 验收证据边界

8. 维护规则