加密

Capgo 提供了强大的端到端加密功能，确保您的应用程序包中的 JavaScript code 和资产在传输和存储过程中受到保护。该加密系统旨在为您提供对应用程序安全性的完全控制，同时保持实时更新的便利性。

概述

Capgo 的加密系统使用行业标准的加密方法来保护您的包免受未经授权的访问。启用加密时，您的包在离开开发环境之前会被加密，并且直到它们被用户设备上的应用程序解密为止。

什么加密实际上保护了什么: 与 OTA 系统相比，只有签名更新,Capgo 加密上传的包之前存储和传输。这保护了存储或传输过程中的包内容，并确保只有您私钥的持有者才能产生有效的加密更新。它并没有 使已发布的 Web 资产无法逆向工程：客户端用于解密更新的公钥被分发在应用程序中，因此一位坚定的攻击者仍然可以提取它并检查包内容的内容。 何时需要加密

何时需要加密

如果您上传一个未加密的捆绑包，视为公共资产。私有通道限制哪些设备接收更新，但它们不会使上传的捆绑包保密。加密有助于在存储和传输时提供更好的保护，并且只有持有私钥的人才能发布有效的加密更新。它不能保证运输的 JavaScript、HTML 或 CSS 一定无法被检查。

威胁模型

Capgo 加密保护了捆绑包的泄露免受 Capgo、存储提供商、CDN 或仅看到加密传递artifact的人的影响。它还防止第三方在没有您的私钥的情况下生成有效的加密更新。由于公共密钥嵌入在分布式应用中，因此客户端可以解密更新，某人如果有您的应用二进制文件并有足够的动机仍然可以恢复恢复检查捆绑包所需的密钥材料。

提示

加密特别重要的场景是：

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

加密的工作原理

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

1. 密钥生成

• 私钥: 在开发环境中安全生成并存储（用于加密）
• 公钥: 从私钥派生并在应用的Capacitor配置中存储（用于解密）
• 会话密钥: 为每次上传包生成的随机AES密钥

2. 加密过程

1. 为每个上传的包生成一个随机的AES会话密钥
2. 使用AES会话密钥对您的包进行加密
3. 计算包的校验和
4. 使用您的RSA私钥对AES会话密钥和校验和进行加密（创建“签名”）
5. 存储加密的包和加密的签名

校验和与AES密钥一起加密，以防止篡改。由于只有您的RSA私钥才能创建此签名，且只有相应的公钥才能解密它，因此这确保了AES会话密钥和预期校验和都是真实的，并且没有被攻击者修改。

3. 解密流程

1. 您的应用程序下载加密的包和加密的签名
2. 使用您的RSA公钥（存储在应用程序中）来解密签名的Capgo SDK
3. 这揭示了AES会话密钥和原始校验和
4. 使用 AES 会话密钥来解密捆绑包
5. 计算并与原始校验和进行比较的解密捆绑包的校验和

即使攻击者截获加密的捆绑包，他们也无法修改 AES 会话密钥或提供虚假的校验和，因为他们需要您的私钥才能创建一个有效的签名，这个签名可以被公钥解密。

提示

RSA不能高效地加密大量数据，因此在实际捆绑包加密时使用 AES，而 RSA则负责加密 AES 密钥并通过校验和签名提供完整性验证。

Capgo vs 其他平台

功能	Capgo	其他 OTA 平台
捆绑包内容	在存储/传输中加密;仍然可以通过反向工程师在应用程序二进制文件中检查	公开可读
安全方法	真正的端到端加密	Code 签名仅
隐私级别	平台可以访问您的 __CAPGO_KEEP_0__	Platform can access your code
内容 + 完整性 + 真实性	完整性 + 真实性仅	为什么这很重要:

在存储/传输中加密;仍然可以通过反向工程师在应用程序二进制文件中检查

• Code signing 仅验证更新未被篡改且来自正确源
• Capgo 加密 保护存储和传递的包并使伪造加密更新更困难，因为攻击者需要您的私钥
• 逆向工程仍然可能 因为客户端包含用于解密和加载更新的公钥

加密方法

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

加密 V2 (当前标准)

• 加密 V2 (当前标准)
• AES-256-GCM用于认证加密
• 提供完整性验证
• 更好的性能和安全性

Encryption V1（已弃用）

• 使用RSA-2048进行密钥加密
• AES-256-CBC用于打包加密
• 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:您的公钥（您的应用程序使用）

这些文件是在您运行命令的当前目录中创建的。

注意

重要存储说明：

• 私钥（.capgo_key_v2): 不要将其提交到版本控制中。该文件应保持安全并仅用于加密上传包时使用。
• 公钥（.capgo_key_v2.pub): 这是安全提交到版本控制的，因为它是您的公钥备份。
• 文件位置: 密钥是在您运行命令的当前目录中创建的。 key create 配置中的公钥
• command: 您必须运行 key save 为了让移动应用程序使用，必须将公钥存储在您的 Capacitor 配置中。

在生产环境中，安全地存储私钥（环境变量，密钥管理服务）并从您的本地项目中删除它。

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

您 必须 将您的公钥保存到 Capacitor 配置中，以便您的移动应用程序可以解密捆绑包：

# 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. 命令将公钥存储在您的 __CAPGO_KEEP_0__ 配置中 key save command stores the public key in your Capacitor config
2. npx cap sync 如果没有这两个步骤,您的应用程序就无法解密加密的更新
3. command stores the public key in your __CAPGO_KEEP_0__ config copies this config to the native layer where the mobile app can access it Without both steps your app won’t be able to decrypt encrypted updates

加密打包

方法 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：手动加密工作流

为了获得更多的控制，您可以手动加密打包：

1. 创建一个 zip 打包：

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

2. 加密包裹：

   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 秘密管理私钥
• Never commit private keys to version control

Key Usage:

• Private Key: Used by CLI for encryption during bundle upload (keep secure)
• Public Key: Stored in app configuration for decryption on device (safe to commit)

Key Rotation

Regularly rotate your encryption keys for enhanced security:

1. Generate new keys:

   # Navigate to desired directory first, then create keys
   mkdir ./new-keys && cd ./new-keys
   npx @capgo/cli@latest key create

2. 将新公钥保存到Capacitor配置:

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

3. 更新您的应用程序配置 使用新公钥

4. 部署更新的应用程序 在上传加密包装之前

安全最佳实践

密钥安全

• 绝不分享私钥 环境或团队成员之间
• 为不同环境（dev，staging，production）使用不同的密钥 定期轮换密钥（建议每6-12个月）
• 安全存储密钥 安全包
• 在解密后始终验证包完整性 监控

使用适当的密钥管理系统

• 安全包 安全包
• 安全包 __CAPGO_KEEP_0__
• 使用 HTTPS __CAPGO_KEEP_1__
• 实现 正确处理解密失败的错误

访问控制

• 限制 对加密密钥的访问仅限授权人员
• 使用基于角色的访问 控制密钥管理操作
• 审计 定期检查和访问密钥
• Implement 正确备份和恢复程序

故障排除加密

常见问题

解密失败：

• 确认私钥与用于加密的公钥匹配
• 检查加密 ivSessionKey 确保您正在使用加密 V2（V1 已不再支持）
• Implement

与密钥相关的错误：

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

性能问题：

• 大型捆绑包可能会花更长时间进行加密/解密
• 考虑使用Delta（清单）更新来减少捆绑包大小
• 监控设备性能在解密期间

调试命令

检查加密状态：

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 模式: 提供了机密性和真实性
• Secure Random: 使用加密安全随机数生成

这使得 Capgo 适合需要遵守:

• GDPR (通用数据保护条例)
• HIPAA (健康保险可移植性和责任法)
• SOC 2 (服务组织控制 2)
• ISO 27001 (信息安全管理)

性能考虑

加密开销

• 打包大小: 加密的包大小约为1-2%的额外大小
• 处理时间: 加密/解密操作会增加极小的延迟
• 内存使用: 加密/解密操作期间的暂时性内存占用增加

优化技巧

• 通过将图像转换为WebP格式来优化打包大小
• 在打包之前最小化JavaScript和CSS文件
• 移除未使用的依赖项和__CAPGO_KEEP_0__
• Remove unused dependencies and code
• 在较旧或较慢的设备上监控设备性能

下一步

• 了解 自定义存储 使用自己的基础设施进行加密
• 探索 频道 在不同环境中管理加密包
• 设置 CI/CD集成 自动化加密部署