加密

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. 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 与其他平台

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

为什么这很重要:

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

加密方法

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

加密V2（当前标准）

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

加密 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)：请勿将其提交到版本控制中。该文件应保持安全并仅用于在上传捆绑包时进行加密。
• 公钥（.capgo_key_v2.pub)：这是安全提交到版本控制的，因为它是您的公钥备份。
• 文件位置：密钥在您运行的命令的当前目录中创建。 key create 公钥在配置中
• File Location您必须运行 key save 以在您的Capacitor配置中存储公钥，才能让移动应用使用。

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

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

您 上下文：Capgo UI 中的 HTML 文本片段（父键 `you_definition`）。页面/区域：Capgo 市场网站。角色：长期市场或法律段落。见于：页面免责声明.astro，页面返回.astro。消息键 `you_definition`（您定义）。 save your public key to the Capacitor config so your mobile app can decrypt bundles:

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

Step 3: Sync Capacitor Platform (Required)

保存公钥后，您必须 必须 同步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)

方法 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 在打包上传期间用于加密（保持安全）
• 公钥: 在设备上进行解密存储在应用配置中（安全提交）

在私钥被泄露后旋转

在私钥被怀疑或确认泄露时，旋转密钥对。 不需要定期轮换日历。这是一个本机密钥迁移，而不是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,然后分发一个包含替换公钥的新原生应用程序版本。

4. 目标新原生版本: 仍在运行旧原生二进制文件的设备无法解密使用替换密钥加密的更新。使用 版本目标 区域: Capgo 解决方案营销页面。角色: 部分或页面标题。见于: 页面解决方案/版本目标.astro。消息键 `solutions_version_targeting_title` (解决方案版本目标标题)。|区域: Capgo 解决方案营销页面。角色: 短 UI 标签或导航项。见于: 页面解决方案/版本目标.astro。消息键 `solutions_version_targeting` (解决方案版本目标)。

5. 来限制替换密钥捆绑包到新原生版本，同时fleet更新通过商店或 MDM。 切换您的上传密钥:

注意事项

如果私钥被泄露，请立即停止使用。使用旧的公钥的现有安装需要在本机存储或 MDM 更新后才能接收使用替换密钥加密的包。

安全最佳实践

密钥安全

• 不要共享私钥 在环境或团队成员之间
• 为不同环境 (开发、测试、生产) 使用不同的密钥 在泄露后旋转密钥
• 在泄露后旋转密钥: 当私钥被怀疑或确认被破坏时，替换密钥对; 日常轮换不需要
• 安全存储密钥 使用适当的密钥管理系统

Bundle 安全

• 始终在解密后验证 bundle 完整性
• 监控 异常下载模式或故障
• 使用 HTTPS 为所有 Bundle URL (移动应用程序必需)
• 实施 __CAPGO_KEEP_0__

访问控制

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

加密故障排除

常见问题

解密失败:

• 确认私钥与用于加密的公钥匹配
• 检查 ivSessionKey 是否正确
• 确保您正在使用Encryption 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适合于需要遵守：

• 《通用数据保护条例》(General Data Protection Regulation)
• 《健康保险可移植性和责任法》(Health Insurance Portability and Accountability Act)
• 《服务组织控制2》(Service Organization Control 2)
• 《信息安全管理体系》(Information Security Management)

性能考虑

加密开销

• 包大小: 加密包大小约为1-2%的开销
• 处理时间: 加密/解密过程对处理时间影响很小
• 内存使用: 加密/解密操作期间临时增加

优化技巧

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

下一步

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

继续加密

加密 __CAPGO_KEEP_0__ 为了计划安全性和合规性，连接它与 合规 在合规中， Capgo 安全扫描器 在Capgo 安全扫描器中产品工作流程 Capgo 安全 在Capgo 安全中产品工作流程 Capgo 信任中心 在Capgo 信任中心中产品工作流程，并且 组织安全 在组织安全中合规细节