加密

Capgo 为您的 app bundle 提供强大的端到端加密，确保您的 JavaScript code 和资源在传输和存储过程中受到保护。这套加密系统旨在让您在享受 Live Updates 便利性的同时，完全掌控应用安全。

概览

Capgo 的加密系统采用行业标准加密方法，保护您的 bundle 免受未经授权的访问。启用加密后，bundle 会在离开您的开发环境前被加密，并一直保持加密，直到由用户设备上的 App 解密。

加密究竟保护了什么: 与仅对更新签名的 OTA 系统不同，Capgo 会在存储和交付前加密上传的 bundle。这能防止 bundle 内容在存储或传输中被随意访问，并确保只有持有您私钥的人才能生成有效的加密更新。它并不能 不会 让已发布的 Web 资源无法被逆向工程：客户端用于解密更新的公钥会随 App 分发，因此执着的攻击者只要投入足够精力，仍可提取公钥并查看 bundle 内容。

何时需要加密

如果您上传未加密的 bundle，请将其视为公开资源。私有 Channel 虽然可以限制哪些设备接收更新，但并不能让上传的 bundle 具有保密性。当您希望在存储和传输中获得更好的保护，或希望只有私钥持有者才能发布有效的加密更新时，加密就很有用。它并不保证已发布的 JavaScript、HTML 或 CSS 永远不会被检查。

威胁模型

Capgo 加密可防止 Capgo、存储提供商、CDN 或任何仅能看到加密交付产物的第三方泄露 bundle。它还能防止第三方在没有您私钥的情况下生成有效的加密更新。由于公钥已嵌入分发的 App 中以便客户端解密更新，因此拥有 App 二进制文件且有足够动机的人仍可能恢复用于检查 bundle 所需的密钥材料。

提示

加密对于以下场景尤为重要：

• 处理敏感数据或业务逻辑的 App
• 具有合规性要求的企业级应用
• 部署在受监管行业中的 App
• 具有严格安全策略的组织

安全模型

关于 Capgo 的保密性

您的 RSA 私钥在您的本地机器上生成并保存。Capgo CLI 绝不会传输您的私钥，Capgo 也不会存储它。Capgo 也不会存储您的完整 RSA 公钥：上传时仅包含一段短 key_id （PEM 主体的头 20 个字符），以便 Channel 可以匹配您使用的密钥对。

加密后的完整 Bundle 以以下形式存储和分发： AES-128-CBC 密文. Capgo 服务、CDN、对象存储以及分发路径上的任何人员，在没有您的私钥的情况下，都无法读取您的 JavaScript、HTML 或资源文件。

对 Capgo 最大程度保密

默认加密已确保 Bundle 的 内容 在 Capgo 存储和传输过程中保持机密。如果您还希望通过将 Update Channel 与特定的商店二进制文件关联，来减少 Capgo 可能获取的信息，请参考以下指南。

使用专用的 Capgo App ID。 设置 plugins.CapacitorUpdater.appId （您的 Capgo app_id) 至一个值，该值 不会 与您的 iOS bundle ID 或 Android application ID 相同。Store 和 MDM 构建会将您的 RSA 公钥嵌入 capacitor.config. 当 Capgo app_id 与 Store 包名匹配时，更容易将 Capgo 应用与包含该公钥的已发布二进制文件关联起来。使用独立的 Capgo 应用 ID 可以避免这种直接关联。

Capgo Builder 和公钥。 Capgo Builder 会将您的项目以 zip 格式上传，并附带 capacitor.config （以及 native tree），包括 plugins.CapacitorUpdater.publicKey 在 key save之后。为了防止公钥出现在 Builder 上传中：

• 当需要对 Capgo 保持机密性时，请在本地或您自己的 CI 中构建 native apps，并避免在配置中包含公钥的情况下通过 Capgo Builder 上传这些 tree， 或
• 使用以下方式添加公钥： key save 仅在必须保护密钥的 Builder 上传完成后， 或
• 如果您依赖 Capgo Builder 进行 Native Build，请将该工作流视为提供了强大的 完整性 (已签名的校验和) 但请勿 不会 在公钥包含在 Builder 上传中后，仍假设 Capgo 具有机密性。

加密 Delta 上传。 除非您使用 @capgo/capacitor-updater 6.14.4 或更高版本 （在受支持的 updater 版本上，加密上传会自动启用部分加密）或传递 --encrypt-partial 开启 bundle upload即使采用部分加密， 文件名 在 delta manifests 中列出的文件名不会被加密；只有每个文件的哈希会经 RSA 封装。

完整性

解密后，更新程序会计算 SHA-256 对 bundle 计算 SHA-256，并将其与从经 RSA 封装的签名中恢复的校验和进行比对。如果不匹配，bundle 会被移除且永远不会被激活：

• Android Android 在解密后检查校验和，并 在……之前 正在解压压缩包。
• iOS 先解密并解压，再验证校验和 在……之前 即可将 bundle 设为 active。

配置公钥后，缺失的校验和或未正确 RSA 签名的校验和都会被拒绝。

密钥处理

对于每次完整 zip 上传，CLI 都会生成一个新的随机 AES-128 会话密钥和 16 字节 IV，使用以下方式加密 bundle： AES-128-CBC，并用您的 RSA-2048 私钥加密 session key，通过 PKCS#1 v1.5 type 1 填充。设备通过应用中内置的 RSA 公钥恢复 AES 密钥。不同的 CLI bundle 上传之间不会复用密钥和 IV。在一次 delta 上传中，所有加密的分片文件共享该次上传的 session key 和 IV。

用于解密的公钥已内置在您发布的 App 中。在通过 updater 所用相同解密路径运行 App 的设备上，可获取明文 bundle 内容，这与 App 包中的其他资源类似。

故障与报告

解密和校验和失败会作为 stats 事件（download_fail, checksum_fail, decrypt_fail）上报至 Capgo stats 端点或您的 自托管统计处理程序. 统计数据由设备端发送；不会根据解密成功或失败向第三方 bundle 托管商报告任何信息。每次尝试通常都是由设备发起的完整下载，因此进行 padding-oracle 类型的探测并不现实，且修改后的明文仍无法通过签名校验。

未来安全加固

未来的重大版本可能会引入带有以下内容的版本化格式： AES-GCM 以及 RSA-PSS 在现有设计的基础上，通过对哈希进行上述处理来实现深度防御。这将是一个增量式的加固步骤，而非针对当前格式的紧急安全修复。

加密工作原理

Capgo 采用混合加密方案，结合了 RSA 和 AES 加密，以实现最佳的安全性和性能：

1. 密钥生成

• 私钥：在开发环境中生成并安全存储（用于加密）
• 公钥：由私钥派生并存储在应用的 Capacitor 配置中（用于解密）
• 会话密钥 (Session Keys)：每次 bundle upload 时生成的随机 AES 密钥

2. 加密流程

1. 每次 bundle upload 时都会生成一个随机的 AES 会话密钥
2. 您的 bundle 使用 AES 会话密钥进行加密
3. 计算 bundle 校验和 (checksum)
4. 使用您的 RSA 私钥对 AES 会话密钥和校验和进行统一加密（即生成“签名”）
5. 存储加密后的 bundle 和加密后的签名

校验和随 AES 密钥一同加密以防止篡改。由于只有您的 RSA 私钥能生成此签名，且只有对应的公钥能对其解密，这确保了 AES 会话密钥和预期的校验和均真实有效，未被攻击者篡改。

3. 解密流程

1. 您的 App 下载加密后的 bundle 和加密后的签名
2. Capgo SDK 使用您存储在 App 中的 RSA 公钥来解密签名
3. 从而获取 AES 会话密钥和原始校验和
4. 使用 AES 会话密钥对 bundle 进行解密
5. 计算解密后 bundle 的校验和，并与原始校验和进行比对以验证完整性

该流程确保即使攻击者拦截了加密的 bundle，也无法篡改 AES 会话密钥或提供伪造的校验和，因为要创建公钥可验证的有效签名，他们需要您的私钥。

提示

RSA 无法高效加密大量数据，因此实际的 bundle 加密使用 AES，而 RSA 负责保护 AES 密钥，并通过校验和签名提供完整性验证。

Capgo vs 其他平台

功能	Capgo	其他 OTA 平台
Bundle 内容	存储/传输时加密；但执着的逆向工程师仍可借助 App 二进制文件进行检查	公开可读
安全方式	真正的端到端加密	仅限 Code 签名
隐私级别	强传输/存储保护；非防逆向工程	平台可以访问您的 code
保护范围	内容 + 完整性 + 真实性	仅限完整性 + 真实性

为什么这很重要：

• Code 签名 仅验证更新未被篡改且来自正确的来源
• Capgo 加密 在存储和传输过程中保护 bundle，由于攻击者需要你的私钥，这使得伪造加密更新变得极其困难
• 逆向工程仍然是可能的 在应用发布后，因为客户端包含了解密并加载更新所需的公钥

加密方法

Capgo 使用 Encryption V2 作为标准加密方法：

加密 V2（当前标准）

• 使用 RSA-4096 以增强安全性
• 使用 AES-256-GCM 进行身份验证加密
• 提供完整性校验
• 更出色的性能与安全性

加密 V1 (已弃用)

• 使用 RSA-2048 进行密钥加密
• 使用 AES-256-CBC 进行 bundle 加密
• 当前 CLI 中已不再提供
• 使用 V1 的旧版应用必须迁移至 V2

危险

当前的 Capgo CLI 已不再支持 Encryption V1。如果您正在使用 V1 加密，请务必迁移至 V2。请参阅 迁移指南 以获取详细说明。

配置加密

步骤 1：生成加密密钥

首先，使用 Capgo CLI 生成您的加密密钥：

# Generate new encryption keys (creates files in current directory)
npx @capgo/cli@latest key create

这将创建：

• .capgo_key_v2：您的私钥（请务必妥善保管！）
• .capgo_key_v2.pub：您的公钥（供您的 App 使用）

这些文件将生成在您运行命令的当前目录下。

注意

重要存储说明：

• 私钥 (.capgo_key_v2)）：切勿将其提交到版本控制中。请妥善保管此文件，仅在 bundle 上传时用于加密。
• 公钥 (.capgo_key_v2.pub)）：该文件可以安全地提交到版本控制，因为它是公钥的备份。
• 文件位置：密钥会生成在你运行以下命令的当前目录中 key create 命令。
• 配置中的公钥：你必须运行 key save 以将公钥存入你的 Capacitor 配置，供移动端 App 使用。

生产环境中，请安全存储私钥（环境变量、密钥管理服务），并在设置完成后从本地项目中移除。

步骤 2：将公钥保存到 Capacitor 配置（必填）

您 必须 将公钥保存到 Capacitor 配置中，以便你的移动应用能解密 bundle：

# Save public key from file to Capacitor config (required)
npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub

# Or save public key data directly
npx @capgo/cli@latest key save --key-data "$CAPGO_PUBLIC_KEY"

步骤 3：同步 Capacitor 平台（必填）

保存公钥后，你 必须 同步 Capacitor 平台，将更新后的配置复制到原生层：

# Sync the platform to copy config to native
npx cap sync

注意

必要步骤:

1. 本指南中介绍的 key save 该命令会将公钥存储在您的 Capacitor 配置中
2. npx cap sync 将此配置复制到原生层，以便移动端 App 访问
3. 如果缺少这两个步骤，您的 App 将无法解密已加密的更新

加密 Bundle

方法 1：上传时加密

最简单的方式是在上传过程中加密：

# Upload with automatic encryption
npx @capgo/cli@latest bundle upload --key-v2

# For external storage, you must encrypt first (see Manual Encryption Workflow below)

方法 2：手动加密工作流

如需更精细的控制，可以手动加密 bundle：

1. 创建一个 zip bundle：

   npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2

2. 加密该 bundle：

   npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM_FROM_STEP_1

3. 上传至您的存储（如 S3）并使用 Capgo 进行注册：

   # First upload the encrypted bundle to your storage (e.g., AWS S3)
   aws s3 cp ./encrypted-bundle.zip s3://your-bucket/encrypted-bundle.zip
   
   # Then register with Capgo using the external URL
   npx @capgo/cli@latest bundle upload --external https://your-storage.com/encrypted-bundle.zip --iv-session-key IV_SESSION_KEY_FROM_STEP_2

密钥管理

安全存储密钥

私钥选项：

1. 基于文件（本地开发）：

   # Key stored as .capgo_key_v2 file in project root
   npx @capgo/cli@latest bundle upload --key-v2

2. 环境变量 (CI/CD):

   # Store in environment variable for CI
   export CAPGO_PRIVATE_KEY="$(cat .capgo_key_v2)"
   npx @capgo/cli@latest bundle upload --key-data-v2 "$CAPGO_PRIVATE_KEY"

公钥配置 (必填):

# Must save public key to Capacitor config for mobile app
npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub

生产环境:

• 将私钥存储在安全的密钥管理服务中 (AWS KMS, Azure Key Vault 等)
• 使用 CI/CD 密钥管理功能来处理私钥
• 切勿将私钥提交至版本控制系统

密钥使用:

• 私钥：CLI 在 bundle upload 时用于加密（请妥善保管）
• 公钥：存储在 App 配置中，用于设备端解密（可安全提交）

私钥泄露后进行轮换

当怀疑或确认私钥泄露时，请轮换密钥对。无需进行常规的定期轮换。这是一次 native-key 迁移，而非仅限 OTA 的变更。

1. 生成新的密钥对：

   npx @capgo/cli@latest key create

2. 将新的公钥保存到您的 Capacitor 配置中：

   npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub

3. 同步并发布原生版本： 运行 npx cap sync，然后分发包含新公钥的新原生 App 版本。

4. 指定新的原生版本： 仍运行旧原生二进制的设备无法解密使用新密钥加密的更新。请使用 版本定向 将使用新密钥的 bundle 限制为仅面向新的原生版本，其余设备则通过应用商店或 MDM 更新。

5. 更换你的 upload secret： 一旦该原生版本上线，就更换 CI 中的私钥，并且只上传面向包含新公钥的原生版本的 bundle。

注意

如果私钥泄露，请立即停止使用。使用旧公钥的现有安装版本需要通过 Native Build 或 MDM 进行更新，才能接收使用新密钥加密的 bundle。

安全最佳实践

密钥安全

• 切勿在环境或团队成员之间 共享私钥
• 为不同环境使用不同密钥 (dev, staging, production)
• 泄露后及时轮换：当怀疑或确认私钥泄露时，请更换密钥对；无需进行常规的定期轮换
• 安全存储密钥 使用合适的密钥管理系统

Bundle 安全

• 务必验证 解密后的 bundle 完整性
• 监控 针对异常的下载模式或失败情况
• 使用 HTTPS 用于所有 bundle URL（移动应用必需）
• 实现 为解密失败做好错误处理

访问控制

• 限制访问 加密密钥仅限授权人员访问
• 使用基于角色的访问控制 进行密钥管理操作
• 审计 定期审计密钥使用与访问情况
• 实现 完善的备份与恢复流程

加密故障排除

常见问题

解密失败原因：

• 验证私钥是否与加密时使用的公钥匹配
• 检查 ivSessionKey 是否正确
• 确保正在使用 Encryption V2（不再支持 V1）

密钥相关错误：

• 确认私钥格式是否正确（PEM 格式）
• 验证密钥在存储或传输过程中未损坏
• 检查密钥在应用配置中是否具有正确的权限

性能问题：

• 较大的 bundle 可能需要更长的加密/解密时间
• 考虑使用 Delta updates 来减小 bundle 体积
• 监控解密过程中的设备性能

调试命令

检查加密状态：

npx @capgo/cli@latest app debug

测试加密/解密工作流：

# Test the complete workflow: zip → encrypt → decrypt → unzip
npx @capgo/cli@latest bundle zip com.example.app --key-v2
npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM --json
npx @capgo/cli@latest bundle decrypt ./encrypted-bundle.zip IV_SESSION_KEY

合规性与标准

Capgo 的加密实现遵循行业标准：

• AES-256：经 FIPS 140-2 认证的加密算法
• RSA-4096：用于密钥保护的强非对称加密
• GCM 模式：同时提供机密性和真实性
• 安全随机数：密码学安全的随机数生成

这使得 Capgo 适用于需要符合以下标准的应用程序：

• GDPR（通用数据保护条例）
• HIPAA（医疗保险可移植性与责任法案）
• SOC 2 (Service Organization Control 2)
• ISO 27001 (信息安全管理)

性能考量

加密开销

• Bundle 体积: 加密后的 bundle 会略微变大（约 1-2% 的开销）
• 处理耗时: 加解密带来的延迟极低
• 内存占用: 加解密操作期间会有短暂上升

优化建议

• 使用 Delta updates 减少加密数据的传输量
• 将图片转换为 WebP 格式以优化 bundle 体积
• 在打包前压缩 JavaScript 和 CSS 文件
• 移除未使用的依赖项和 code
• 在旧款或低速设备上监控性能表现

下一步

• 了解 自定义存储 在自有基础设施中使用加密功能
• 探索 通道 跨环境管理加密 bundle
• 设置 CI/CD 集成 实现加密部署自动化

加密后的下一步

如果你正在使用 加密 来规划安全与合规，请结合 合规性 了解合规部分的实现细节， Capgo 安全扫描器 了解 Capgo Security Scanner 的产品工作流， Capgo 安全 适用于 Capgo Security 中的产品工作流， Capgo 信任中心 适用于 Capgo Trust Center 中的产品工作流，以及 组织安全 适用于 Organization Security 中的实现细节。