加密
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
Capgo 为您的 app bundle 提供强大的端到端加密,确保您的 JavaScript code 和资源在传输和存储过程中受到保护。这套加密系统旨在让您在享受 Live Updates 便利性的同时,完全掌控应用安全。
概览
“概览”章节Capgo 的加密系统采用行业标准加密方法,保护您的 bundle 免受未经授权的访问。启用加密后,bundle 会在离开您的开发环境前被加密,并一直保持加密,直到由用户设备上的 App 解密。
加密究竟保护了什么: 与仅对更新签名的 OTA 系统不同,Capgo 会在存储和交付前加密上传的 bundle。这能防止 bundle 内容在存储或传输中被随意访问,并确保只有持有您私钥的人才能生成有效的加密更新。它并不能 不会 让已发布的 Web 资源无法被逆向工程:客户端用于解密更新的公钥会随 App 分发,因此执着的攻击者只要投入足够精力,仍可提取公钥并查看 bundle 内容。
安全模型
关于 Capgo 的保密性
章节标题:“关于 Capgo 的机密性”RSA 私钥在你的机器上生成并保存。Capgo CLI 绝不会传输你的私钥,Capgo 也不会存储它。Capgo 同样不会存储你的完整 RSA 公钥:上传内容只包含一个短 key_id (PEM 正文的前 20 个字符),以便 channel 能匹配你使用的密钥对。
加密后的完整 bundle 按以下形式存储和分发: AES-128-CBC 密文。Capgo 服务、CDN、对象存储,以及分发路径上只能看到托管产物的任何人,在没有你的私钥时都无法读取你的 JavaScript、HTML 或资源文件。
对 Capgo 最大程度保密
章节标题为“对 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 (以及原生目录树),包括 plugins.CapacitorUpdater.publicKey 之后 key save。要让公钥不出现在 Builder 上传内容中:
- 当需要向 Capgo 保密时,请在本地或自己的 CI 中构建原生应用,并在公钥仍位于配置中时,避免通过 Capgo Builder 上传这些目录树, 或
- 添加公钥时,请
key save确保所有不得暴露密钥的 Builder 上传任务已完成之后, 或 - 如果您依赖 Capgo Builder 进行原生构建,请将工作流视为提供强 完整性 (签名校验和),但 不会 一旦公钥包含在 Builder 上传中,请勿假设 Capgo 能提供机密性。
加密增量上传。 除非您使用 @capgo/capacitor-updater 6.14.4 或更高版本 (支持的更新器版本在加密上传时会自动启用部分加密),否则增量(部分)文件主体为明文,或者传入 --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 类型 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. 密钥生成
章节标题为“1. 密钥生成”- 私钥:在开发环境中安全生成并存储(用于加密)
- 公钥:由私钥派生并存储在应用的 Capacitor 配置中(用于解密)
- 会话密钥:每次上传 bundle 时生成的随机 AES 密钥
2. 加密流程
章节标题为“2. 加密过程”- 每次上传 bundle 时都会生成一个随机的 AES 会话密钥
- 您的 bundle 使用 AES 会话密钥加密
- 计算 bundle 校验和
- 使用您的 RSA 私钥将 AES 会话密钥和校验和一起加密(生成“签名”)
- 存储加密后的 bundle 和加密后的签名
校验和与 AES 密钥一起加密,以防篡改。由于只有您的 RSA 私钥能生成此签名,且只有对应的公钥能解密,因此可确保 AES 会话密钥和预期校验和真实有效,且未被攻击者修改。
3. 解密流程
章节标题:“3. 解密流程”- 您的 App 下载加密后的 bundle 和加密后的签名
- Capgo SDK 使用您的 RSA 公钥(存储在 App 中)解密签名
- 从而得到 AES 会话密钥和原始校验和
- 使用 AES 会话密钥解密 bundle
- 计算解密后 bundle 的校验和,并与原始校验和比对,以验证完整性
该流程确保即使攻击者拦截了加密的 bundle,也无法篡改 AES 会话密钥或提供伪造的校验和,因为要创建公钥可验证的有效签名,他们需要您的私钥。
Capgo vs 其他平台
标题为“Capgo vs 其他平台”的章节| 功能 | Capgo | 其他 OTA 平台 |
|---|---|---|
| Bundle 内容 | 存储/传输时加密;但执着的逆向工程师仍可借助 App 二进制文件进行检查 | 公开可读 |
| 安全方法 | 真正的端到端加密 | 仅 Code 签名 |
| 隐私级别 | 强大的传输/存储保护;非防逆向工程 | 平台可访问您的 code |
| 保护 | 内容 + 完整性 + 真实性 | 仅完整性 + 真实性 |
为什么这很重要:
- Code 签名 仅验证更新未被篡改且来自正确来源
- Capgo 加密 在 bundle 存储和传输过程中提供保护,并让伪造加密更新变得困难得多,因为攻击者需要拿到你的私钥
- 逆向工程仍然可能 在应用发布之后,因为客户端中包含了解密和加载更新所需的公钥
加密方法
标题为“加密方法”的章节Capgo 使用 Encryption V2 作为标准加密方法:
加密 V2(当前标准)
标题为“Encryption V2(当前标准)”的章节- 使用 RSA-4096 增强安全性
- 采用 AES-256-GCM 进行认证加密
- 提供完整性校验
- 更好的性能与安全性
加密 V1 (已弃用)
章节标题为“Encryption V1(已弃用)”- 使用 RSA-2048 进行密钥加密
- 使用 AES-256-CBC 进行 bundle 加密
- 当前 CLI 中不再提供
- 使用 V1 的旧版应用必须迁移到 V2
配置加密
标题为“设置加密”的部分第 1 步:生成加密密钥
标题为“步骤 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:你的公钥(供你的应用使用)
这些文件会创建在你运行命令的当前目录中。
步骤 2:将公钥保存到 Capacitor 配置(必填)
标题为“步骤 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 directlynpx @capgo/cli@latest key save --key-data "$CAPGO_PUBLIC_KEY"步骤 3:同步 Capacitor 平台(必填)
标题为“步骤 3:同步 Capacitor 平台(必填)”的章节保存公钥后,你 必须 同步 Capacitor 平台,将更新后的配置复制到原生层:
# Sync the platform to copy config to nativenpx cap sync加密 Bundle
标题为“加密 Bundle”的章节方法 1:上传时加密
标题为“方法 1:上传时加密”的章节最简单的方式是在上传过程中加密:
# Upload with automatic encryptionnpx @capgo/cli@latest bundle upload --key-v2
# For external storage, you must encrypt first (see Manual Encryption Workflow below)方法 2:手动加密工作流
标题为“方法 2:手动加密工作流”的章节如需更精细的控制,可以手动加密 bundle:
-
创建一个 zip bundle:
终端窗口 npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2 -
加密该 bundle:
终端窗口 npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM_FROM_STEP_1 -
上传到你的存储(如 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 URLnpx @capgo/cli@latest bundle upload --external https://your-storage.com/encrypted-bundle.zip --iv-session-key IV_SESSION_KEY_FROM_STEP_2
密钥管理
“密钥管理”章节安全存储密钥
“安全存储密钥”章节私钥选项:
-
基于文件(本地开发):
终端窗口 # Key stored as .capgo_key_v2 file in project rootnpx @capgo/cli@latest bundle upload --key-v2 -
环境变量(CI/CD):
终端窗口 # Store in environment variable for CIexport 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 appnpx @capgo/cli@latest key save --key ./.capgo_key_v2.pub生产环境:
- 将私钥存储在安全的密钥管理服务中(如 AWS KMS、Azure Key Vault 等)
- 使用 CI/CD 密钥管理功能来处理私钥
- 切勿将私钥提交到版本控制中
密钥用途:
- 私钥:由 CLI 在上传 bundle 时用于加密(请妥善保管)
- 公钥:存储在应用配置中,用于设备端解密(可安全提交)
私钥泄露后轮换
章节标题:“私钥泄露后轮换”当怀疑或确认私钥泄露时,请轮换密钥对。无需定期按日历轮换。这是原生密钥迁移,而非仅 OTA 变更。
-
生成替换密钥对:
终端窗口 npx @capgo/cli@latest key create -
将替换公钥保存至您的 Capacitor 配置:
终端窗口 npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub -
同步并发布原生版本: 运行
npx cap sync,然后分发包含新公钥的新原生 App 版本。 -
指定新的原生版本: 仍运行旧原生二进制的设备无法解密使用新密钥加密的更新。请使用 版本定向 将使用新密钥的 bundle 限制为仅面向新的原生版本,其余设备则通过应用商店或 MDM 更新。
-
更换你的 upload secret: 一旦该原生版本上线,就更换 CI 中的私钥,并且只上传面向包含新公钥的原生版本的 bundle。
安全最佳实践
“安全最佳实践”章节密钥安全
章节标题为“密钥安全”- 切勿共享私钥 在环境或团队成员之间
- 使用不同的密钥 用于不同环境(dev、staging、production)
- 泄露后轮换:当怀疑或确认私钥已泄露时,替换密钥对;无需按日历定期轮换
- 安全存储密钥 使用合适的密钥管理系统
Bundle 安全
标题为“Bundle 安全”的章节- 务必验证 解密后的 bundle 完整性
- 监控 针对异常的下载模式或失败情况
- 使用 HTTPS 用于所有 bundle URL(移动应用必需)
- 实现 为解密失败做好错误处理
访问控制
“访问控制”章节- 限制访问 加密密钥仅限授权人员访问
- 使用基于角色的访问控制 进行密钥管理操作
- 审计 定期审计密钥使用与访问情况
- 实现 完善的备份与恢复流程
加密故障排除
“加密故障排除”章节常见问题
章节标题为“常见问题”解密失败:
- 确认私钥与用于加密的公钥匹配
- 检查
ivSessionKey是否正确 - 确保您使用的是 Encryption V2(V1 已不再支持)
密钥相关错误:
- 确认私钥格式正确(PEM 格式)
- 验证密钥在存储/传输过程中未损坏
- 检查应用配置中密钥是否具有正确的权限
性能问题:
- 大型 bundle 的加密/解密可能需要更长时间
- 考虑使用 Delta 更新来减小 bundle 大小
- 监控解密过程中的设备性能
调试命令
标题为“调试命令”的章节检查加密状态:
npx @capgo/cli@latest app debug测试加密/解密工作流:
# Test the complete workflow: zip → encrypt → decrypt → unzipnpx @capgo/cli@latest bundle zip com.example.app --key-v2npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM --jsonnpx @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(服务组织控制 2)
- ISO 27001(信息安全管理体系)
性能考量
标题为“性能考量”的章节加密开销
标题为“加密开销”的章节- Bundle 大小:加密后的 Bundle 会略微增大(约 1-2% 的开销)
- 处理时间:加密/解密带来的延迟极小
- 内存占用:在加密/解密操作期间会短暂增加
优化建议
“优化技巧”章节- 使用 Delta updates 减少加密数据的传输量
- 将图片转换为 WebP 格式以优化 bundle 体积
- 在打包前压缩 JavaScript 和 CSS 文件
- 移除未使用的依赖项和 code
- 在较旧或较慢的设备上监控设备性能
下一步
“后续步骤”章节加密后的下一步
标题为“加密后的下一步”的章节如果你正在使用 加密 来规划安全与合规,请结合 合规性 了解合规部分的实现细节, Capgo 安全扫描器 了解 Capgo Security Scanner 的产品工作流, Capgo 安全 适用于 Capgo Security 中的产品工作流, Capgo 信任中心 适用于 Capgo Trust Center 中的产品工作流,以及 组织安全 适用于 Organization Security 中的实现细节。