加密

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

概述

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

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

威胁模型

威胁模型

__CAPGO_KEEP_0__在存储和传输之前将上传的捆绑包加密。这保护了捆绑包内容免受存储或传输过程中的非法访问，并确保只有持有您的私钥的人才能发布有效的加密更新。

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

提示

加密特别重要的场景包括:

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

加密原理

Capgo uses a hybrid encryption approach that combines RSA and AES encryption for optimal security and performance:

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与其他平台的比较

功能	Capgo	其他OTA平台
打包内容	在存储/传输中加密；仍然可以通过应用程序二进制文件被一个有决心的逆向工程师检查	公开可读
安全方法	全端到端加密	Code 只有签名
隐私等级	强大的传输/存储保护; 不是反向工程保护	平台可以访问您的 code
保护	内容 + 完整性 + 真实性	完整性 + 真实性

为什么这很重要：

• Code 签名 只验证更新没有被篡改并且来自正确的源
• Capgo 加密 保护了存储和传输的捆绑包，并使伪造的加密更新变得更加困难，因为攻击者需要您的私钥
• 逆向工程仍然可能 因为客户端包含用于解密和加载更新的公钥，应用程序一旦发布就无法逆向工程

加密方法

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

加密 V2（当前标准）

• 使用 AES-256-GCM 进行认证加密
• 提供完整性验证
• 提供更好的性能和安全性
• 加密 V2 (Current Standard)

加密 V1 (已弃用)

• 使用 RSA-2048 进行密钥加密
• 使用 AES-256-CBC 进行包加密
• 不再在当前 CLI 中可用
• 使用 V1 的遗留应用程序必须迁移到 V2

危险

加密 V1 在当前 Capgo CLI 中不再受支持。如果您正在使用 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): never 将其提交到版本控制。该文件应保密并仅用于在上传捆绑包时进行加密。
• 公钥（.capgo_key_v2.pub): 这是安全提交到版本控制的，因为它是您的公钥备份。
• 文件位置: 键将在您运行命令的当前目录中创建。 key create 配置中的公钥
• : 您必须运行以将公钥存储在您的__CAPGO_KEEP_0__配置中，才能让移动应用使用。 key save to store the public key in your Capacitor config for the mobile app to use.

文件位置：

步骤 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. 这个 key save 命令将公钥存储在您的Capacitor配置中
2. npx cap sync 将此配置复制到本机层，移动应用程序可以访问它
3. 如果没有这两个步骤，应用程序就无法解密加密的更新

加密捆绑包

方法 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)

Method 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 秘密管理私钥
• 不要将私钥提交到版本控制

密钥使用:

• 私钥: CLI用于bundle上传加密（保持安全）
• 公钥: 在设备上进行解密时存储在应用配置中（安全提交）

密钥轮换

定期轮换您的加密密钥以获得更好的安全性：

1. 生成新密钥：

   # 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. 部署更新的应用 在上传加密的捆绑包之前使用新密钥

安全最佳实践

密钥安全

• 不要将私钥 在环境或团队成员之间共享
• 为不同环境（开发、测试、生产）使用不同的密钥 使用不同的密钥
• 定期轮换密钥 (建议每 6-12 个月轮换一次)
• 安全存储密钥 使用适当的密钥管理系统

安全打包

• 始终验证 解密后检查打包完整性
• 监控 异常下载模式或失败
• 使用 HTTPS 所有打包 URL (移动应用必需)
• 正确处理解密失败的错误 访问控制

仅授权人员访问加密密钥

• 定期审计密钥使用和访问 正确备份和恢复程序
• Implement proper error handling for decryption failures
• Access Control Section titled “Access Control”
• Limit access to encryption keys to authorized personnel only

故障排除加密

常见问题

解密失败：

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

密钥相关错误：

• 确认私钥格式正确（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模式:提供机密性和真实性的加密
• 安全随机数:用于生成安全随机数的加密

使得Capgo适合于需要遵守的应用程序:

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

性能考虑

加密开销

• 捆绑大小: 加密捆绑包略大（约1-2%开销）
• 处理时间: 加密/解密会增加极小的延迟
• 内存使用: 加密/解密操作期间临时增加

优化技巧

• 使用 Delta (清单) 更新来最小化加密数据传输
• 通过将图像转换为 WebP 格式来优化您的捆绑包大小
• 在捆绑之前最小化 JavaScript 和 CSS 文件
• 移除未使用的依赖项和 code
• 在较旧/较慢的设备上监控设备性能

下一步

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