加密

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)

:

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

Save the new public key to Capacitor config:

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

更新应用配置 使用新公钥
部署更新的应用 在上传加密的包之前使用新密钥

安全最佳实践

密钥安全

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

安全打包

始终验证 解密后检查打包完整性
监控异常下载模式或失败
使用 HTTPS 为所有打包 URL (移动应用程序必需)
Implement proper error handling for decryption failures

Access Control

Limit access Limit access
Use role-based access Use role-based access
Audit Audit
Implement Implement

故障排除加密

常见问题

解密失败：

确认私钥与用于加密的公钥匹配
检查 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 模式:提供了机密性和真实性的同时
Secure Random:提供了安全的随机数生成

This makes 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 安全扫描器 Capgo 安全扫描器中的产品工作流 Capgo 安全 Capgo 安全中的产品工作流 Capgo 信任中心 Capgo 信任中心中的产品工作流组织安全组织安全的实现细节