网络安全事故很少来自“忘了用 HTTPS”这么简单。测试环境为了抓包临时信任用户安装的 CA、业务域名范围写得过宽、证书异常被统一忽略、WebView 与原生网络栈策略不一致都会把临时调试口变成生产风险。HarmonyOS 的网络连接安全配置用于声明连接信任边界在 HarmonyOS 7/API 26 适配中更应该把它当作版本化安全契约而不是发版前的配置补丁。本文给出一套从威胁建模、环境分离、证书信任、明文阻断、错误处理到自动化验收的实践。配置字段请以目标 SDK 官方文档为准示例重点是策略结构和工程门禁。一、先建立连接资产清单没有域名台账就无法知道应该信任谁。按业务域、用途、数据级别和所有者登记所有外连目标。interfaceEndpointAsset{host:stringpurpose:stringdataLevel:PUBLIC|ACCOUNT|SENSITIVEowner:stringenvironments:ArrayDEV|TEST|PRODthirdParty:boolean}把 API、图片 CDN、上传、推送、地图、支付、埋点和 Web 页面都纳入。动态拼接的任意域名应视为高风险而不是“方便扩展”。二、默认拒绝按需放行网络策略应从“默认只允许安全连接”开始对少数必要目标做精确规则。不要写一个覆盖所有子域甚至所有主机的例外。interfaceConnectionRule{domain:stringincludeSubdomains:booleancleartextAllowed:booleantrust:ArraySYSTEM_CA|APP_CA|USER_CA}constproductionRule:ConnectionRule{domain:api.example.com,includeSubdomains:false,cleartextAllowed:false,trust:[SYSTEM_CA]}实际配置文件格式、资源路径和字段名称必须按官方“网络连接安全配置”文档生成上面的 TypeScript 只是审查模型。三、生产环境通常不应信任用户 CA用户安装证书适合企业受管场景或开发抓包却也可能允许中间人解密流量。生产消费者应用应明确评估是否需要信任用户 CA。typeBuildChanneldebug|qa|releasefunctionallowedTrust(channel:BuildChannel):string[]{if(channeldebug)return[SYSTEM_CA,DEV_CA]if(channelqa)return[SYSTEM_CA,QA_CA]return[SYSTEM_CA]}关键点是构建隔离调试证书、测试域名和宽松规则不得仅靠运行时开关隐藏而应不进入 release 包。四、环境配置物理分离开发、测试、预发布和生产的信任根与域名不同。建议用独立资源文件或构建变体生成最终配置并对产物做静态检查。{channel:release,allowedHosts:[api.example.com,upload.example.com,static.examplecdn.com],allowCleartext:false,allowUserCA:false}CI 不只检查源码还要解包最终 HAP确认真实生效的配置没有测试域名和测试证书。五、明文 HTTP 例外必须可到期旧设备或局域网硬件可能暂时只支持 HTTP。例外要限定域名、用途、负责人和删除日期。interfaceSecurityException{ticket:stringhost:stringreason:stringowner:stringexpiresAt:stringmitigation:string}functionexpired(e:SecurityException,today:string):boolean{returne.expiresAttoday}不能用“所有明文允许”解决一个局域网地址。对敏感数据即使业务紧急也不应通过明文传输。六、证书校验失败必须失败关闭遇到证书过期、域名不匹配或链不可信时客户端应中止连接展示可恢复提示并上报非敏感错误分类。typeTlsFailure|CERT_EXPIRED|HOST_MISMATCH|UNTRUSTED_CHAIN|PROTOCOL_UNSUPPORTEDfunctionuserMessage(error:TlsFailure):string{return安全连接失败请检查时间或网络后重试}不要提供“继续访问”按钮也不要在捕获异常后自动降级到 HTTP。七、不要自定义一个不完整的证书校验器为了实现证书锁定或私有 CA有团队会自己解析证书却漏掉有效期、域名、用途、撤销与链构建。优先使用系统信任和官方配置能力。interfacePinSet{host:stringcurrentPins:string[]backupPins:string[]expiresAt:string}如确需锁定必须准备至少一个备份 Pin、证书轮换流程、远端应急策略和过期提醒。锁定不是“越严越好”配置失误会让全部用户断网。八、Web 与原生网络栈统一策略应用可能同时使用 HTTP 客户端、Web 组件、图片加载器、音视频 SDK 和第三方支付 SDK。任何一个组件绕过策略都会形成短板。interfaceStackAuditItem{stack:HTTP_CLIENT|ARKWEB|IMAGE|MEDIA|THIRD_PARTYusesHttps:booleanfollowsTrustPolicy:booleanhandlesTlsErrorSafely:boolean}Web 页面重定向、iframe、图片和下载域也要纳入域名台账不要只验证首页 URL。九、日志保持可诊断但不泄密安全连接失败需要定位但日志不能记录完整令牌、Cookie、请求体和证书私钥。interfaceSafeNetworkLog{hostHash:stringerrorClass:stringnetworkType:stringappVersion:stringpolicyVersion:stringtimestamp:number}域名是否可直接记录取决于业务敏感性查询参数通常应删除。客户端日志与服务端握手日志通过时间窗和请求 ID 关联。十、自动化负向测试比“请求成功”更重要测试环境准备有效证书、过期证书、错误域名、自签名证书、用户 CA、中间证书缺失和 HTTP 重定向等场景。interfaceSecurityCase{name:stringendpoint:stringexpected:ALLOW|BLOCKexpectedError?:TlsFailure}constcases:SecurityCase[][{name:valid-chain,endpoint:https://valid.test,expected:ALLOW},{name:expired,endpoint:https://expired.test,expected:BLOCK,expectedError:CERT_EXPIRED},{name:http-redirect,endpoint:https://redirect-http.test,expected:BLOCK}]每次更新证书、网络库、SDK 或安全配置后自动回归。十一、证书轮换要双轨演练服务端换证前客户端要确认新证书链在系统信任范围内如使用锁定先发布同时接受新旧 Pin 的版本再换服务端最后移除旧 Pin。typeRotationStageADD_NEW|SWITCH_SERVER|REMOVE_OLDinterfaceRotationPlan{stage:RotationStage minimumClientVersion:stringrollbackDeadline:string}把证书到期监控纳入运维不要等线上握手失败才发现。十二、CI 安全门禁network-security-gate:checks:-release_has_no_test_ca-release_has_no_debug_host-cleartext_is_disabled-exceptions_are_not_expired-negative_tls_cases_pass门禁输出应能定位规则来源和所有者。对配置文件的任何修改要求安全评审而不是普通文本变更直接合并。十三、上线检查清单已维护全部网络栈和外连域名台账默认拒绝明文连接例外精确且可到期release 构建不包含调试 CA、测试域名和宽松规则生产是否信任用户 CA 已有明确结论证书异常失败关闭不回退 HTTP原生、ArkWeb、图片、媒体和第三方 SDK 策略一致日志不记录令牌、Cookie、请求体和敏感参数有证书轮换与回滚演练负向 TLS 用例进入 CI最终 HAP 产物经过静态审计。结语网络连接安全配置的价值是把“客户端到底信任谁”从散落在代码和调试习惯里的隐式行为变成可审查、可测试、可轮换的显式契约。HarmonyOS 7 适配时同时治理域名、信任根、构建变体、错误处理和证书轮换才能避免为一次抓包或临时兼容留下长期后门。官方参考网络连接安全配置https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/network-connection-security-configurationHarmonyOS 版本说明https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/changelogs-600ArkWeb 页面加载问题定位https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/web-page-loading
HarmonyOS 7 新特性（四十四）｜网络安全配置：证书信任与负向门禁
网络安全事故很少来自“忘了用 HTTPS”这么简单。测试环境为了抓包临时信任用户安装的 CA、业务域名范围写得过宽、证书异常被统一忽略、WebView 与原生网络栈策略不一致都会把临时调试口变成生产风险。HarmonyOS 的网络连接安全配置用于声明连接信任边界在 HarmonyOS 7/API 26 适配中更应该把它当作版本化安全契约而不是发版前的配置补丁。本文给出一套从威胁建模、环境分离、证书信任、明文阻断、错误处理到自动化验收的实践。配置字段请以目标 SDK 官方文档为准示例重点是策略结构和工程门禁。一、先建立连接资产清单没有域名台账就无法知道应该信任谁。按业务域、用途、数据级别和所有者登记所有外连目标。interfaceEndpointAsset{host:stringpurpose:stringdataLevel:PUBLIC|ACCOUNT|SENSITIVEowner:stringenvironments:ArrayDEV|TEST|PRODthirdParty:boolean}把 API、图片 CDN、上传、推送、地图、支付、埋点和 Web 页面都纳入。动态拼接的任意域名应视为高风险而不是“方便扩展”。二、默认拒绝按需放行网络策略应从“默认只允许安全连接”开始对少数必要目标做精确规则。不要写一个覆盖所有子域甚至所有主机的例外。interfaceConnectionRule{domain:stringincludeSubdomains:booleancleartextAllowed:booleantrust:ArraySYSTEM_CA|APP_CA|USER_CA}constproductionRule:ConnectionRule{domain:api.example.com,includeSubdomains:false,cleartextAllowed:false,trust:[SYSTEM_CA]}实际配置文件格式、资源路径和字段名称必须按官方“网络连接安全配置”文档生成上面的 TypeScript 只是审查模型。三、生产环境通常不应信任用户 CA用户安装证书适合企业受管场景或开发抓包却也可能允许中间人解密流量。生产消费者应用应明确评估是否需要信任用户 CA。typeBuildChanneldebug|qa|releasefunctionallowedTrust(channel:BuildChannel):string[]{if(channeldebug)return[SYSTEM_CA,DEV_CA]if(channelqa)return[SYSTEM_CA,QA_CA]return[SYSTEM_CA]}关键点是构建隔离调试证书、测试域名和宽松规则不得仅靠运行时开关隐藏而应不进入 release 包。四、环境配置物理分离开发、测试、预发布和生产的信任根与域名不同。建议用独立资源文件或构建变体生成最终配置并对产物做静态检查。{channel:release,allowedHosts:[api.example.com,upload.example.com,static.examplecdn.com],allowCleartext:false,allowUserCA:false}CI 不只检查源码还要解包最终 HAP确认真实生效的配置没有测试域名和测试证书。五、明文 HTTP 例外必须可到期旧设备或局域网硬件可能暂时只支持 HTTP。例外要限定域名、用途、负责人和删除日期。interfaceSecurityException{ticket:stringhost:stringreason:stringowner:stringexpiresAt:stringmitigation:string}functionexpired(e:SecurityException,today:string):boolean{returne.expiresAttoday}不能用“所有明文允许”解决一个局域网地址。对敏感数据即使业务紧急也不应通过明文传输。六、证书校验失败必须失败关闭遇到证书过期、域名不匹配或链不可信时客户端应中止连接展示可恢复提示并上报非敏感错误分类。typeTlsFailure|CERT_EXPIRED|HOST_MISMATCH|UNTRUSTED_CHAIN|PROTOCOL_UNSUPPORTEDfunctionuserMessage(error:TlsFailure):string{return安全连接失败请检查时间或网络后重试}不要提供“继续访问”按钮也不要在捕获异常后自动降级到 HTTP。七、不要自定义一个不完整的证书校验器为了实现证书锁定或私有 CA有团队会自己解析证书却漏掉有效期、域名、用途、撤销与链构建。优先使用系统信任和官方配置能力。interfacePinSet{host:stringcurrentPins:string[]backupPins:string[]expiresAt:string}如确需锁定必须准备至少一个备份 Pin、证书轮换流程、远端应急策略和过期提醒。锁定不是“越严越好”配置失误会让全部用户断网。八、Web 与原生网络栈统一策略应用可能同时使用 HTTP 客户端、Web 组件、图片加载器、音视频 SDK 和第三方支付 SDK。任何一个组件绕过策略都会形成短板。interfaceStackAuditItem{stack:HTTP_CLIENT|ARKWEB|IMAGE|MEDIA|THIRD_PARTYusesHttps:booleanfollowsTrustPolicy:booleanhandlesTlsErrorSafely:boolean}Web 页面重定向、iframe、图片和下载域也要纳入域名台账不要只验证首页 URL。九、日志保持可诊断但不泄密安全连接失败需要定位但日志不能记录完整令牌、Cookie、请求体和证书私钥。interfaceSafeNetworkLog{hostHash:stringerrorClass:stringnetworkType:stringappVersion:stringpolicyVersion:stringtimestamp:number}域名是否可直接记录取决于业务敏感性查询参数通常应删除。客户端日志与服务端握手日志通过时间窗和请求 ID 关联。十、自动化负向测试比“请求成功”更重要测试环境准备有效证书、过期证书、错误域名、自签名证书、用户 CA、中间证书缺失和 HTTP 重定向等场景。interfaceSecurityCase{name:stringendpoint:stringexpected:ALLOW|BLOCKexpectedError?:TlsFailure}constcases:SecurityCase[][{name:valid-chain,endpoint:https://valid.test,expected:ALLOW},{name:expired,endpoint:https://expired.test,expected:BLOCK,expectedError:CERT_EXPIRED},{name:http-redirect,endpoint:https://redirect-http.test,expected:BLOCK}]每次更新证书、网络库、SDK 或安全配置后自动回归。十一、证书轮换要双轨演练服务端换证前客户端要确认新证书链在系统信任范围内如使用锁定先发布同时接受新旧 Pin 的版本再换服务端最后移除旧 Pin。typeRotationStageADD_NEW|SWITCH_SERVER|REMOVE_OLDinterfaceRotationPlan{stage:RotationStage minimumClientVersion:stringrollbackDeadline:string}把证书到期监控纳入运维不要等线上握手失败才发现。十二、CI 安全门禁network-security-gate:checks:-release_has_no_test_ca-release_has_no_debug_host-cleartext_is_disabled-exceptions_are_not_expired-negative_tls_cases_pass门禁输出应能定位规则来源和所有者。对配置文件的任何修改要求安全评审而不是普通文本变更直接合并。十三、上线检查清单已维护全部网络栈和外连域名台账默认拒绝明文连接例外精确且可到期release 构建不包含调试 CA、测试域名和宽松规则生产是否信任用户 CA 已有明确结论证书异常失败关闭不回退 HTTP原生、ArkWeb、图片、媒体和第三方 SDK 策略一致日志不记录令牌、Cookie、请求体和敏感参数有证书轮换与回滚演练负向 TLS 用例进入 CI最终 HAP 产物经过静态审计。结语网络连接安全配置的价值是把“客户端到底信任谁”从散落在代码和调试习惯里的隐式行为变成可审查、可测试、可轮换的显式契约。HarmonyOS 7 适配时同时治理域名、信任根、构建变体、错误处理和证书轮换才能避免为一次抓包或临时兼容留下长期后门。官方参考网络连接安全配置https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/network-connection-security-configurationHarmonyOS 版本说明https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/changelogs-600ArkWeb 页面加载问题定位https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/web-page-loading
