为 Capacitor 应用实现 SSL Pinning

SSL pinning 通过在应用内直接验证服务器证书，保护您的应用免受中间人 (MITM) 攻击等安全威胁。 如果没有它，攻击者可能会拦截敏感数据或篡改通信。以下是其重要性以及如何有效实现的方法：

为什么 SSL Pinning 至关重要：

防止 MITM 攻击： 拦截 API 调用。
强化安全性： 通过已知值验证服务器证书。
符合 App Store 要求： 助力满足 Apple 和 Google 的安全标准。
建立用户信任： 确保传输过程中的用户数据安全。

实现 SSL Pinning 的关键步骤：

选择合适的 Plugin： 确保兼容 iOS 和 Android。
配置您的 App： 将证书数据嵌入 App 设置中。
特定平台的设置：
- Android： 使用 network_security_config.xml 来定义证书固定（certificate pins）。
- iOS: 调整 Info.plist 并在运行时验证证书。
测试你的配置： 使用以下工具模拟攻击： Charles Proxy 以验证安全性。
证书管理： 定期更新证书并保留备份，以避免服务中断。

快速对比：Android 与 iOS 的 SSL Pinning

功能	Android	iOS
配置文件	`network_security_config.xml`	`Info.plist`
证书位置	`res/raw` 目录	App bundle
验证方式	基于 XML 的配置	ATS 与运行时校验
更新流程	手动或自动	手动或自动

小贴士： 使用以下工具自动更新证书，例如 Capgo 以确保无需重新构建 App 也能平滑、安全地过渡。这能防止服务中断，并持续符合应用商店指南。

SSL pinning 是任何 Capacitor App 用来保护 API 通信安全并保护用户数据的必备手段。立即开始实施，提升你的 App 安全性。

TLS/SSL Certificate Pinning 详解

配置要求

在你的 App 中配置 SSL pinning Capacitor 应用中需要周密的规划和精确的配置。以下是有效实现证书固定（Certificate Pinning）需要了解的关键点。

选择合适的 SSL Pinning 插件

第一步是选择一个在 iOS 和 Android 上都能良好运行，且具备强大安全特性的插件。对于 Capacitor 应用， @capgo/capacitor-ssl-pinning 它能将 iOS 和 Android 上的 CapacitorHttp HTTPS 连接固定到 bundle 中的证书。对比插件时，请考虑以下因素：

平台兼容性: 确保插件在 iOS 和 Android 设备上均能正常工作。
证书管理: 选择能够简化证书处理流程的插件。
便捷更新: 寻找支持在无需重新构建整个 App 的情况下更新证书的插件。
性能考量：评估该插件可能对应用的运行速度和响应能力产生的影响。

配置您的 Capacitor 应用

Capacitor Framework 文档网站

选定插件后，下一步是配置您的 Capacitor 应用以启用 SSL pinning。以下是配置示例：

// Example: capacitor.config.ts
{
  appId: 'com.example.app',
  plugins: {
    SSLPinning: {
      certs: ['cert1', 'cert2'],
      validateCertificates: true,
      allowBackup: false
    }
  }
}

建议逐步推出这些变更，以确保用户平稳过渡。完成通用配置后，请针对 Android 和 iOS 进行平台特定的调整，以完成最终部署。

平台特定设置

为了有效防御 MITM 攻击，设置 SSL pinning 需要针对 Android 和 iOS 进行定制化配置。

Android 端实现

在 Android 上，SSL pinning 涉及设置网络安全配置并管理证书。具体操作如下：

创建网络安全配置

首先创建一个名为 network_security_config.xml 在 res/xml 目录下：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">api.example.com</domain>
        <pin-set>
            <pin digest="SHA-256">your_certificate_hash</pin>
            <!-- Backup pin -->
            <pin digest="SHA-256">backup_certificate_hash</pin>
        </pin-set>
    </domain-config>
</network-security-config>

更新 AndroidManifest.xml 文件

在你的文件中引用新创建的网络安全配置 AndroidManifest.xml 文件：
```
<application
    android:networkSecurityConfig="@xml/network_security_config"
    ...>
```
添加证书文件

将所需的证书文件 (.cer 或 .pem) 于 res/raw 目录下。

iOS 端实现

对于 iOS，SSL pinning 需要通过修改 App Transport Security (ATS) 设置并实现运行时证书验证来完成。请遵循以下步骤：

在 Info.plist 中设置 ATS

将以下配置添加到应用的 Info.plist 文件：

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <false/>
    <key>NSExceptionDomains</key>
    <dict>
        <key>api.example.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSPinnedDomains</key>
            <true/>
        </dict>
    </dict>
</dict>

在 Code 中初始化 SSL Pinning

使用以下 code 代码片段在应用初始化期间启用 SSL pinning：

import { HTTP } from '@ionic-native/http/ngx';

export class AppComponent {
  constructor(private http: HTTP) {
    this.initializeSSLPinning();
  }

  async initializeSSLPinning() {
    try {
      await this.http.setSSLCertMode('pinned');
      console.log('SSL Pinning initialized successfully');
    } catch (error) {
      console.error('SSL Pinning initialization failed:', error);
    }
  }
}

Android 与 iOS 实现方式对比

以下是 Android 和 iOS 在 SSL pinning 实现上的快速对比：

功能	Android	iOS
配置文件	`network_security_config.xml`	`Info.plist`
证书位置	`res/raw` 目录	App bundle
验证方式	XML 配置	ATS 与运行时校验
插件支持	Native + 自定义插件	Native + 自定义插件

接下来，我们将深入探讨测试策略和常见错误，帮助您确保 SSL pinning 配置既可靠又安全。

测试与修复

测试 SSL pinning 配置对于防止中间人 (MITM) 攻击至关重要。本文将介绍如何确保实现过程的安全，并协助你排查常见问题。

MITM 攻击测试

你可以使用 Charles Proxy 等代理工具来模拟 MITM 攻击，从而验证你的 SSL pinning 配置是否生效。

使用 Charles Proxy 进行测试

请按照以下步骤使用 Charles Proxy 进行测试：

在设备上安装 Charles 根证书。
在 Charles 设置中启用 SSL Proxying。
将你的 API 域名添加到 SSL proxying 列表中。
配置设备，使流量通过 Charles 代理进行路由。

如果 SSL pinning 实现正确，在测试期间你应该能在应用日志中看到证书校验错误。

网络配置测试

使用以下 code 代码片段来验证使用 pinned certificate 的连接情况：

// Validate pinned certificate connection
try {
    const response = await Http.get({
        url: 'https://api.example.com/test',
        headers: { 'Content-Type': 'application/json' }
    });
    console.log('Connection successful');
} catch (error) {
    console.error('Certificate validation failed:', error);
}

常见错误解决方案

以下是一些典型的 SSL pinning 问题及其解决方法：

错误类型	常见原因	解决方案
证书不匹配	配置中的 Hash 值错误	使用以下工具验证证书 Hash： OpenSSL.
路径问题	证书位置错误	请检查各平台特定的证书路径。
格式问题	证书格式无效	将证书转换为正确的格式（例如 PEM 或 DER）。
网络超时	Pinning 配置错误	请检查您的网络安全设置。

验证证书 Hash

为确保证书 Hash 与您的配置匹配，请使用以下 OpenSSL 命令：

# Generate the correct certificate hash
openssl x509 -in certificate.pem -pubkey -noout | \
openssl rsa -pubin -outform der | \
openssl dgst -sha256 -binary | base64

解决所有错误后，请确保您的证书更新流程运行正常。

证书更新测试

在配置中同时包含主证书和备用证书，以防止更新期间服务中断。

更新测试流程

以下是测试证书轮换的一个示例：

// Rotate certificates
const certificates = {
    current: 'sha256/current_certificate_hash',
    backup: 'sha256/backup_certificate_hash'
};

// Test both certificates
async function validateCertificates() {
    try {
        await testConnection(certificates.current);
        console.log('Primary certificate valid');
    } catch {
        try {
            await testConnection(certificates.backup);
            console.log('Backup certificate valid');
        } catch {
            console.error('All certificates invalid');
        }
    }
}

监控证书过期情况

定期检查证书是否过期，以避免服务中断：

# Check certificate expiration date
openssl x509 -enddate -noout -in certificate.pem

最后，请在各种条件下测试您的配置，包括稳定的 WiFi、移动数据、离线场景以及网络切换，以确保安全性和功能的稳健性。

SSL Pinning 管理

完成 SSL pinning 配置后，下一步就是管理证书和密钥的 pinning，以长期维持强大的安全性。

证书 Pinning 与密钥 Pinning 的区别

在 SSL pinning 方面，主要有两种方法：证书 pinning 和公钥 pinning。它们各有优势，特别是在 Capacitor 应用:

功能	证书固定	公钥固定
安全级别	高 – 锁定整个证书	极高 – 仅锁定公钥
维护成本	每次证书更新均需同步更新	更新频率较低，证书续期后仍有效
实现方式	实现更简单	初始配置较复杂
存储占用	占用空间较大	存储需求极低
更新频率	每次证书续期	仅在公钥变更时

这份对比可以帮助你判断哪种方式最符合应用的长期维护策略。

自动化证书更新

保持证书更新对于保障 API 通信安全至关重要。Capgo 通过自动化这些更新提供了简化的解决方案，无需重新向应用商店提交。它提供以下功能：

采用速度快: 更新会分阶段发布并跟踪，24 小时内采用率可达 95% [1].
加密传输: 更新全程端到端加密。
实时监控: 分析数据可帮助你了解更新成功情况。

如何实现：

设置自动化更新
集成 Capgo 的 CI/CD pipeline 以自动处理证书更新。Capgo 方案起步价为 $12/月，包含 OTA 更新及每月约 15 次 Native Build。超出部分的构建时长将通过积分按分钟计费。
追踪证书指标
使用 Capgo 的 analytics dashboard 监控关键指标，例如目前为 82% 的全球更新成功率 [1].

这些措施有助于保护您的 App 免受潜在的 MITM（中间人）攻击。

App Store 安全指南

Apple App Store 和 Google Play Store 对 SSL pinning 都有严格的安全要求。以下是它们的具体要求概览：

Apple App Store：

必须使用端到端加密来更新证书。
必须对证书进行严格验证。
在审核过程中需要提供安全相关文档。

Google Play Store：

更新必须使用经批准的机制。
证书管理必须保持透明。
必须具备回退机制。

Capgo 的解决方案在符合所有这些要求的同时，还能实现即时更新 [1]. 为了构建稳健的安全方案，建议将传统的应用商店更新与通过 Capgo 进行的实时更新相结合。这种混合策略可确保您的应用在保持安全合规的同时，避免不必要的延迟。

总结

为了保护您的 Capacitor 应用免受 MITM 攻击，实施 SSL pinning 是必不可少的。通过将受信任的证书数据直接嵌入应用中，您可以显著增强 API 通信的安全性。

为了成功实施，请务必注意以下关键点：

证书管理： 务必定期更新并监控您的证书，以防止潜在的服务中断。
开发工作流： 在测试环境中加入绕过机制，同时确保生产环境构建使用严格的安全协议。
平台指南： 遵守 Apple App Store 和 Google Play Store 的安全要求以确保合规。

SSL pinning 在保护用户数据和维护应用完整性方面起着关键作用。结合前文讨论的更广泛的安全措施，它可以帮助构建更安全的应用环境。

常见问题

::: 常见问题

如果在 Capacitor 应用中不使用 SSL pinning，可能会带来哪些风险？

如果 Capacitor 应用未配置 SSL pinning，该应用将更容易受到 中间人 (MITM) 攻击。这些攻击允许恶意攻击者拦截并篡改应用与服务器之间传输的数据。这可能导致用户凭据等敏感信息泄露，或者 API 密钥.

此外，如果没有 SSL pinning，攻击者可以使用伪造或受损的证书冒充受信任的服务器，从而增加数据泄露的风险。通过实施 SSL pinning，您可以确保通信安全，并保护用户免受这些风险的影响。 :::

::: 常见问题

在 Capacitor 应用中，Android 和 iOS 实现及维护 SSL pinning 的主要区别是什么？

由于各自独特的 API 和安全机制，Android 和 iOS 的 SSL pinning 工作方式略有不同。

在 Android，开发者通常依赖 OkHttp 等网络库或使用原生设置来配置 SSL pinning。然而，一旦需要更新已绑定的证书，通常意味着需要发布应用的新版本。

在 iOS，SSL pinning 通常通过 URLSession 或借助第三方库来处理。与 Android 一样，任何证书更新都需要谨慎管理，以确保 API 通信不会中断。

两个平台都需要持续关注证书过期和更新，以保持 API 连接的安全。定期测试对于及早发现兼容性问题以及防范 中间人 (MITM) 攻击至关重要。 :::

::: 常见问题

如何自动化 SSL 证书更新，并确保我的 Capacitor 应用符合 App Store 的安全要求？

虽然本文不会深入探讨自动化 SSL 证书更新或确保符合 App Store 安全指南的具体工具与策略，但你可以通过以下步骤来提升应用的安全性。其中一个有效的措施是实现 SSL Pinning 到你的 Capacitor 应用中。这有助于保护你的应用免受 中间人 (MITM) 攻击，从而防止敏感数据泄露。

为了管理 Live Update 并简化应用维护，像 Capgo 这样的平台可以彻底改变开发流程。它们让你在遵守 App Store 规范的同时更轻松地发布更新，为开发者和用户提供更流畅的体验。 :::

继续阅读：Capacitor 应用的 SSL Pinning

如果你正在使用 为 Capacitor 应用实现 SSL Pinning 以规划安全与合规，并将其与加密以了解 Encryption 中的实现细节，合规性有关 Compliance 中的实现细节， Capgo 安全扫描器关于 Capgo Security Scanner 的产品工作流， Capgo 安全性关于 Capgo Security 的产品工作流，以及 Capgo 信托中心关于 Capgo Trust Center 的产品工作流。