Encryption

Capgo provides robust end-to-end encryption for your app bundles, ensuring that your JavaScript code and assets are protected during transmission and storage. This encryption system is designed to give you complete control over your app’s security while maintaining the convenience of live updates.

Overview

Capgo’s encryption system uses industry-standard cryptographic methods to protect your bundles from unauthorized access. When encryption is enabled, your bundles are encrypted before leaving your development environment and remain encrypted until they’re decrypted by your app on the user’s device.

True End-to-End Encryption: Unlike other OTA update platforms that only sign updates (leaving the code publicly readable), Capgo provides true end-to-end encryption. This means only your users can decrypt your updates - no one else, including Capgo itself. Your bundle content remains completely private and unreadable throughout the entire delivery process.

ヒント

Encryption is particularly important for:

• Apps handling sensitive data or business logic
• Enterprise applications with compliance requirements
• Apps deployed in regulated industries
• Organizations with strict security policies

How Encryption Works

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

1. Key Generation

• Private Key: Generated and stored securely in your development environment (used for encryption)
• Public Key: Derived from your private key and stored in your app’s Capacitor config (used for decryption)
• Session Keys: Random AES keys generated for each bundle upload

2. Encryption Process

1. A random AES session key is generated for each bundle upload
2. Your bundle is encrypted using the AES session key
3. The bundle checksum is calculated
4. Both the AES session key and checksum are encrypted together using your RSA private key (creating the “signature”)
5. The encrypted bundle and encrypted signature are stored

The checksum is encrypted alongside the AES key to prevent tampering. Since only your RSA private key can create this signature, and only the corresponding public key can decrypt it, this ensures that both the AES session key and the expected checksum are authentic and haven’t been modified by an attacker.

3. Decryption Process

1. Your app downloads the encrypted bundle and encrypted signature
2. The Capgo SDK uses your RSA public key (stored in the app) to decrypt the signature
3. This reveals the AES session key and the original checksum
4. The AES session key is used to decrypt the bundle
5. A checksum of the decrypted bundle is calculated and compared with the original checksum for integrity verification

This process ensures that even if an attacker intercepts the encrypted bundle, they cannot modify the AES session key or provide a fake checksum, because they would need your private key to create a valid signature that the public key can decrypt.

ヒント

RSA cannot encrypt large amounts of data efficiently, so AES is used for the actual bundle encryption while RSA secures the AES key and provides integrity verification through checksum signing.

Capgo vs Other Platforms

Feature	Capgo	Other OTA Platforms
Bundle Content	Fully encrypted (unreadable)	Publicly readable
Security Method	True end-to-end encryption	Code signing only
Privacy Level	Zero-knowledge (even Capgo can’t read your code)	Platform can access your code
Protection	Content + integrity + authenticity	Integrity + authenticity only

Why This Matters:

• Code signing only verifies that updates haven’t been tampered with and come from the right source
• End-to-end encryption ensures that your actual code content remains private and unreadable during transmission and storage
• With Capgo’s true end-to-end encryption, only your users can decrypt updates - no one else, including Capgo itself

Encryption Methods

Capgo uses Encryption V2 as the standard encryption method:

Encryption V2 (Current Standard)

• Uses RSA-4096 for enhanced security
• AES-256-GCM for authenticated encryption
• Provides integrity verification
• Better performance and security

Encryption V1 (Deprecated)

• Uses RSA-2048 for key encryption
• AES-256-CBC for bundle encryption
• No longer available in the current CLI
• Legacy apps using V1 must migrate to V2

危険

Encryption V1 is no longer supported in the current Capgo CLI. If you’re using V1 encryption, you must migrate to V2. See the migration guide for detailed instructions.

Setting Up Encryption

Step 1: Generate Encryption Keys

First, generate your encryption keys using the Capgo CLI:

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

This creates:

• .capgo_key_v2: Your private key (keep this secure!)
• .capgo_key_v2.pub: Your public key (used by your app)

These files are created in the current directory where you run the command.

警告

Important Storage Notes:

• Private Key (.capgo_key_v2): Never commit this to version control. This file should be kept secure and used only for encryption during bundle uploads.
• Public Key (.capgo_key_v2.pub): This is safe to commit to version control as it’s a backup of your public key.
• File Location: Keys are created in the current directory where you run the key create command.
• Public Key in Config: You must run key save to store the public key in your Capacitor config for the mobile app to use.

For production use, store the private key securely (environment variables, key management services) and remove it from your local project after setup.

Step 2: Save Your Public Key to Capacitor Config (Required)

You must 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)

After saving the public key, you must sync the Capacitor platform to copy the updated config to the native layer:

# Sync the platform to copy config to native
npx cap sync

警告

Required Steps:

1. The key save command stores the public key in your Capacitor config
2. npx cap sync copies this config to the native layer where the mobile app can access it
3. Without both steps, your app won’t be able to decrypt encrypted updates

Encrypting Bundles

Method 1: Encrypt During Upload

The simplest way is to encrypt during the upload process:

# 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: Manual Encryption Workflow

For more control, you can manually encrypt bundles:

1. Create a zip bundle:

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

2. Encrypt the bundle:

   npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM_FROM_STEP_1

3. Upload to your storage (e.g., S3) and register with 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 Management

Storing Keys Securely

Private Key Options:

1. File-based (local development):

   # Key stored as .capgo_key_v2 file in project root
   npx @capgo/cli@latest bundle upload --key-v2

2. Environment variable (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"

Public Key Setup (Required):

# Must save public key to Capacitor config for mobile app
npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub

Production Environment:

• Store private keys in secure key management services (AWS KMS, Azure Key Vault, etc.)
• Use CI/CD secret management for private keys
• Never commit private keys to version control

Key Usage:

• Private Key: Used by CLI for encryption during bundle upload (keep secure)
• Public Key: Stored in app configuration for decryption on device (safe to commit)

Key Rotation

Regularly rotate your encryption keys for enhanced security:

1. Generate new keys:

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

2. Save the new public key to Capacitor config:

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

3. Update your app configuration with the new public key

4. Deploy the updated app before uploading encrypted bundles with the new key

Security Best Practices

Key Security

• Never share private keys between environments or team members
• Use different keys for different environments (dev, staging, production)
• Rotate keys regularly (recommended: every 6-12 months)
• Store keys securely using proper key management systems

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

• Limit access to encryption keys to authorized personnel only
• Use role-based access for key management operations
• Audit key usage and access regularly
• Implement proper backup and recovery procedures

Troubleshooting Encryption

Common Issues

Decryption failures:

• Verify the private key matches the public key used for encryption
• Check that the ivSessionKey is correct
• Ensure you’re using Encryption V2 (V1 is no longer supported)

Key-related errors:

• Confirm the private key format is correct (PEM format)
• Verify the key hasn’t been corrupted during storage/transfer
• Check that the key has proper permissions in your app configuration

Performance issues:

• Large bundles may take longer to encrypt/decrypt
• Consider using differential updates to reduce bundle sizes
• Monitor device performance during decryption

Debug Commands

Check encryption status:

npx @capgo/cli@latest app debug

Test encryption/decryption workflow:

# 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

Compliance and Standards

Capgo’s encryption implementation follows industry standards:

• AES-256: FIPS 140-2 approved encryption algorithm
• RSA-4096: Strong asymmetric encryption for key protection
• GCM Mode: Provides both confidentiality and authenticity
• Secure Random: Cryptographically secure random number generation

This makes Capgo suitable for applications requiring compliance with:

• GDPR (General Data Protection Regulation)
• HIPAA (Health Insurance Portability and Accountability Act)
• SOC 2 (Service Organization Control 2)
• ISO 27001 (Information Security Management)

Performance Considerations

Encryption Overhead

• Bundle size: Encrypted bundles are slightly larger (~1-2% overhead)
• Processing time: Encryption/decryption adds minimal latency
• Memory usage: Temporary increase during encryption/decryption operations

Optimization Tips

• Use differential updates to minimize encrypted data transfer
• Optimize your bundle size by converting images to WebP format
• Minimize JavaScript and CSS files before bundling
• Remove unused dependencies and code
• Monitor device performance on older/slower devices

Next Steps

• Learn about Custom Storage to use encryption with your own infrastructure
• Explore Channels to manage encrypted bundles across environments
• Set up CI/CD Integration to automate encrypted deployments