加密

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

概述

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

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

When You Need Encryption

If you upload a bundle without encryption, treat it as a public asset. Private channels limit which devices receive an update, but they do not make the uploaded bundle confidential. Encryption is useful when you want better protection in storage and transit and when you want only holders of the private key to be able to publish valid encrypted updates. It does not guarantee that shipped JavaScript, HTML, or CSS can never be inspected.

Threat Model

Capgo encryption protects against bundle disclosure by Capgo, storage providers, CDNs, or anyone who only sees the encrypted delivery artifact. It also prevents third parties from generating valid encrypted updates without your private key. Because the public key is embedded in the distributed app so the client can decrypt updates, someone who has your app binary and enough motivation can still recover the key material needed to inspect the bundle.

Tip

Encryption is particularly important for:

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

加密原理

Capgo 使用一种混合加密方法，结合RSA和AES加密，实现最佳的安全性和性能：

1. 密钥生成

• : 在开发环境中生成并安全存储（用于加密）公钥
• : 从私钥派生并在应用的__CAPGO_KEEP_0__配置中存储（用于解密）: Derived from your private key and stored in your app’s Capacitor config (used for decryption)
• : 为每次上传包生成的随机AES密钥会话密钥

2. 加密过程

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

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

3. 解密过程

1. 您的应用程序下载加密的捆绑包和加密的签名
2. The Capgo SDK uses your RSA public key (stored in the app) to decrypt the signature
3. 这会揭示AES会话密钥和原始校验和
4. 使用AES会话密钥来解密捆绑包
5. 计算并与原始校验和进行比较以验证整体性

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

提示

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

Capgo vs Other Platforms

功能	Capgo	其他OTA平台
Bundle Content	Encrypted in storage/transit; still inspectable by a determined reverse engineer with the app binary	Publicly readable
Security Method	True end-to-end encryption	Code signing only
Privacy Level	Strong delivery/storage protection; not anti-reverse-engineering	Platform can access your code
Protection	Content + integrity + authenticity	Integrity + authenticity only

Why This Matters:

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

加密方法

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

加密 V2（当前标准）

• 使用 RSA-4096 提供增强的安全性
• 使用 AES-256-GCM 进行认证加密
• 提供完整性验证
• 提供更好的性能和安全性

Encryption V1 (Deprecated)

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

警告

当前Capgo CLI中不再支持V1加密。如果您正在使用V1加密，请务必迁移到V2。详细指南请参见 迁移指南 设置加密

标题：设置加密

标题：步骤1：生成加密密钥

First, generate your encryption keys using the Capgo CLI:

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

:您的私钥（请务必保密！)

• .capgo_key_v2__CAPGO_KEEP_0__ __CAPGO_KEEP_1__
• .capgo_key_v2.pub: __CAPGO_KEEP_0__ (用于您的应用)

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

注意

重要存储注意事项：

• : __CAPGO_KEEP_1__ (.capgo_key_v2): never 将其提交到版本控制中。该文件应保持安全并仅用于加密上传捆绑包时使用。
• : __CAPGO_KEEP_2__ (.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 平台（必需）

保存公钥后， 您 sync the Capacitor platform to copy the updated config to the native layer:

# 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)

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

Key Usage:

• 私钥: 由 CLI 用于上传捆绑包时的加密（保持安全）
• 公钥: 存储在应用配置中用于设备上的解密（安全提交）

Key Rotation

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

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. 部署更新的应用程序 在上传加密包装之前

安全最佳实践

密钥安全

• Never share private keys 在环境或团队成员之间不共享私钥
• 为不同环境 (开发, 测试, 生产) 使用不同的密钥 定期轮换密钥 (推荐每 6-12 个月)
• 使用适当的密钥管理系统 安全打包
• 安全打包 始终在解密后验证

包的完整性

• 确保安全 确保安全
• 监控 异常下载模式或失败
• 使用 HTTPS 所有捆绑包 URL (移动应用程序所必需)
• 实现 正确的错误处理

加密失败

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

故障排除加密

常见问题

解密失败：

• 验证私钥与用于加密的公钥匹配
• 检查 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 (信息安全管理)

性能考虑

加密开销

• Bundle size: 加密的捆绑包稍微大一些（约1-2%开销）
• Processing time: 加密/解密增加的延迟很小
• Memory usage: 加密/解密操作期间的暂时性内存占用

优化提示

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

下一步

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

继续从加密

如果您正在使用 加密 与 合规 为了在合规中实现的细节 Capgo 安全扫描器 为了在Capgo 安全扫描器中的产品工作流程 Capgo 安全 为了在Capgo 安全中的产品工作流程 Capgo 信任中心 在 Capgo 信任中心中了解产品工作流程， 组织安全 了解组织安全的实施细节。