一、背景介绍

ArkWeb（方舟Web）提供的Web组件，是鸿蒙应用中用于加载并展示Web页面内容的核心组件，其应用场景覆盖多类开发需求，具体如下：

1. 应用集成Web页面：应用可在界面中嵌入Web组件加载Web页面内容，有效降低开发成本，提升开发与运维效率。
2. 浏览器网页浏览场景：浏览器类应用可通过Web组件打开第三方Web页面，支持无痕浏览、广告拦截等核心功能。
3. 小程序场景：小程序宿主应用可借助Web组件实现小程序页面渲染、同层渲染、视频托管等核心功能。

当应用通过ArkWeb组件加载HTTPS协议URL（如https://www.baidu.com）时，在TLS握手校验阶段，ArkWeb会调用系统预置的CA根证书，对服务端返回的证书链进行完整性、合法性校验。

若校验失败（常见于服务器部署自签名证书的场景，报错日志详见图示），ArkWeb会通过onSslErrorEventReceive与onSslErrorEvent两个回调接口通知应用，应用需在回调中进行合规处理。

二、核心回调接口说明

两个回调接口声明如下，详情可参考：事件-Web-ArkTS 组件-ArkWeb（方舟Web）-应用框架 – 华为HarmonyOS开发者

2.1 onSslErrorEventReceive

onSslErrorEventReceive(callback: Callback<OnSslErrorEventReceiveEvent>)

通知用户加载资源时发生SSL错误，只支持主资源。

如果需要支持子资源，请使用OnSslErrorEvent接口。

说明

• 主资源：浏览器加载网页的入口文件，通常是HTML文档。
• 子资源：主资源中引用的依赖文件，由主资源解析过程中遇到特定标签时触发加载。
• 应用程序需要调用handler.handleCancel()或handler.handleConfirm()处理该回调，如果没有处理该回调则默认取消资源加载。handleConfirm()或者handleCancel()的行为可能会被记录下来，以便为将来的SSL错误做出响应。
• 应用程序可以用于显示自定义错误页面或静默记录问题。

系统能力： SystemCapability.Web.Webview.Core

参数：

2.2 onSslErrorEvent

onSslErrorEvent(callback: OnSslErrorEventCallback)

通知用户加载资源（主资源+子资源）时发生SSL错误，如果只想处理主资源的SSL错误，请用isMainFrame字段进行区分。

说明

• 主资源：浏览器加载网页的入口文件，通常是HTML文档。
• 子资源：主资源中引用的依赖文件，由主资源解析过程中遇到特定标签时触发加载。

系统能力： SystemCapability.Web.Webview.Core

参数：

展开

三、mixedMode混合内容模式说明

Web组件加载HTTPS URL时，若页面资源、脚本中包含HTTP协议内容，会引入安全风险。ArkWeb提供mixedMode属性用于配置混合内容加载策略，具体配置参考官方文档：Enums-Web-ArkTS 组件-ArkWeb（方舟Web）-应用框架 – 华为HarmonyOS开发者

MixedMode

混合内容模式。

系统能力： SystemCapability.Web.Webview.Core

四、不安全实现及风险分析

HTTPS协议的安全性核心依赖证书链校验、安全TLS协议及加密算法。以下为两种典型的不安全实现方式，均会引入中间人攻击风险，导致通信数据被劫持、篡改或泄露。

4.1 SSL错误回调处理不当

收到SSL错误通知时，若直接忽略错误并调用event.handler.handleConfirm()继续加载，会绕过证书校验机制，直接引入中间人攻击风险。

不安全示例代码：

正确实现方式：不实现onSslErrorEventReceive或onSslErrorEvent回调（系统默认取消资源加载）；或在回调中调用event.handler.handleCancel()主动取消加载，阻断不安全连接。

正确示例代码：

4.2 mixedMode配置不当

将mixedMode配置为MixedMode.All（宽松模式），允许加载HTTP与HTTPS混合内容，会导致HTTPS通信的安全性被破坏，引入中间人攻击风险。

不安全示例代码：

正确实现方式：将mixedMode配置为MixedMode.None（严格模式），同时推动服务器将所有HTTP资源链接修改为HTTPS协议，规避混合内容安全风险。

正确示例代码：

五、安全建议

基于上述分析，为保障Web组件加载URL过程中的网络通信安全，结合鸿蒙应用开发规范，提出以下安全建议：

1. SSL错误回调处理：禁止在onSslErrorEventReceive或onSslErrorEvent回调中调用event.handler.handleConfirm()，建议使用系统默认配置（不实现回调），或主动调用handleCancel()取消加载。
2. mixedMode配置：禁止将mixedMode配置为MixedMode.All，建议使用系统默认配置，或显式配置为MixedMode.None，从根源规避混合内容安全风险。

六、参考文档

• ArkWeb Web组件事件说明：事件-Web-ArkTS 组件-ArkWeb（方舟Web）-应用框架 – 华为HarmonyOS开发者
• ArkWeb Web组件mixedMode配置：Enums-Web-ArkTS 组件-ArkWeb（方舟Web）-应用框架 – 华为HarmonyOS开发者

其他鸿蒙应用安全编码专题文章请参考：

https://developer.huawei.com/consumer/cn/blog//topic/03207416677214221