加密

复制一个包含安装步骤和本插件的完整 Markdown 指南的配置提示。

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

概述

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

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

加密原理

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

Capgo 加密流程

1. 密钥生成

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

2. 加密流程

为每次上传的捆绑包生成一个随机 AES 会话密钥
使用 AES 会话密钥对捆绑包进行加密
The bundle checksum is calculated
使用您的RSA私钥（生成“签名”）同时对AES会话密钥和校验和进行加密
存储加密的包和加密的签名

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

3. 解密过程

您的应用程序下载加密的包和加密的签名
Capgo SDK 使用您的RSA公钥（存储在应用程序中）解密签名
这揭示了AES会话密钥和原始校验和
使用AES会话密钥解密包
计算解密包的校验和并与原始校验和进行比较以进行完整性验证

此过程确保即使攻击者截获了加密的包，他们也无法修改AES会话密钥或提供假的校验和，因为他们需要您的私钥才能创建一个有效的签名，公钥才能解密

Capgo与其他平台

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

为什么这很重要：

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

加密方法

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

加密 V2（当前标准）

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

Encryption V1 (Deprecated)

使用RSA-2048进行密钥加密
使用AES-256-CBC进行包加密
不再在当前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:您的公钥（由您的应用使用）

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

步骤 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：上传时加密

最简单的方法是将文件在上传过程中进行加密：

# 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: 手动加密工作流程

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

创建一个 zip 捆绑包：

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

加密捆绑包：

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 URL
npx @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 root
npx @capgo/cli@latest bundle upload --key-v2

环境变量 (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 私钥管理服务
永不将私钥提交到版本控制

密钥使用:

私钥: Used by CLI for encryption during bundle upload (keep secure)
公钥: Stored in app configuration for decryption on device (safe to commit)

在私钥被泄露后旋转

在私钥被泄露或确认被泄露时，旋转密钥pair。不需要定期轮换。这是一个原生密钥迁移，而不是OTA-仅限更改。

生成替换密钥pair：
终端窗口
```
npx @capgo/cli@latest key create
```
将替换的公钥保存到您的Capacitor配置：
终端窗口
```
npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub
```
同步并发布一个原生版本： 运行 npx cap sync, 然后分发一个新的原生应用程序版本，包含替换的公钥。
目标新的原生版本： 仍在运行旧原生二进制文件的设备无法解密使用替换密钥加密的更新。使用版本目标来限制替换密钥捆绑包到新的原生版本，同时fleet的其余部分通过商店或MDM更新。
切换您的上传密钥： 一旦原生版本发布后，替换私钥在CI中，仅上传目标原生版本包含替换公钥的捆绑包。

安全最佳实践

关键安全

不要与团队成员或环境共享私钥 为不同环境（开发、测试、生产）使用不同的密钥
在私钥被怀疑或确认被破坏时，替换密钥对 在私钥被怀疑或确认被破坏时，替换密钥对
使用适当的密钥管理系统安全存储密钥__CAPGO_KEEP_0__
__CAPGO_KEEP_0__ __CAPGO_KEEP_0__

Bundle Security

Always verify bundle integrity after decryption
Monitor for unusual download patterns or failures
Use HTTPS for all bundle URLs (required for mobile apps)
Implement proper error handling for decryption failures

Access Control

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

加密故障排除

常见问题

解密失败：

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

密钥相关错误：

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

性能问题：

大型捆绑包可能需要更长时间进行加密/解密
考虑使用 Delta（清单）更新来减少捆绑包大小
__CAPGO_KEEP_0__

调试命令

检查加密状态：

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 approved encryption algorithm
RSA-4096: 强大的非对称加密用于密钥保护
GCM 模式: 提供了机密性和真实性的同时
安全随机数: 使用安全的随机数生成

This makes Capgo 适合于需要遵守:

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

性能考虑

加密开销

打包大小：加密的包体约略大于原始包体（约1-2%的开销）
处理时间：加密/解密过程中增加的延迟极小
内存使用：加密/解密过程中临时增加的内存占用

优化技巧

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

下一步

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

从加密开始

加密 来规划安全性和合规性,连接它与 合规性来查看合规性实施细节 for the implementation detail in Compliance, Capgo 安全扫描器为产品工作流程在 Capgo 安全扫描器中 Capgo 安全为产品工作流程在 Capgo 安全中 Capgo 信任中心为产品工作流程在 Capgo 信任中心, 和组织安全为组织安全实施细节