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.

What Encryption Actually Protects: Unlike OTA systems that only sign updates, Capgo encrypts the uploaded bundle before storage and delivery. This protects the bundle contents from casual access in storage or transit and ensures only someone with your private key can produce a valid encrypted update. It does not make shipped web assets impossible to reverse engineer: the public key used by the client to decrypt updates is distributed in the app, so a determined attacker can still extract it and inspect bundle contents with enough effort.

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:

• 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.

Tip

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	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 signing only verifies that updates haven’t been tampered with and come from the right source
• Capgo encryption protects the bundle while it is stored and delivered and makes forged encrypted updates much harder because the attacker would need your private key
• Reverse engineering is still possible after the app ships, because the client contains the public key needed to decrypt and load the update

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

Danger

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.

Caution

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

Caution

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)

Rotate after a private-key compromise

Rotate the key pair when the private key is suspected or confirmed compromised. A routine calendar rotation is not required. This is a native-key migration, not an OTA-only change.

1. Generate a replacement key pair:

   npx @capgo/cli@latest key create

2. Save the replacement public key to your Capacitor config:

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

3. Sync and ship a native release: Run npx cap sync, then distribute a new native app version containing the replacement public key.

4. Target the new native version: Devices still running the old native binary cannot decrypt updates encrypted with the replacement key. Use Version Targeting to restrict replacement-key bundles to the new native version while the rest of the fleet updates through the store or MDM.

5. Switch your upload secret: As soon as that native release is live, replace the private key in CI and upload only bundles targeted to native versions that contain the replacement public key.

Caution

If the private key is compromised, stop using it immediately. Existing installs with the old public key need a native store or MDM update before they can receive bundles encrypted with the replacement 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 after a compromise: replace the key pair when the private key is suspected or confirmed compromised; a routine calendar rotation is not required
• 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 Delta (manifest) 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 Delta (manifest) 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

Keep going from Encryption

If you are using Encryption to plan security and compliance, connect it with Compliance for the implementation detail in Compliance, Capgo Security Scanner for the product workflow in Capgo Security Scanner, Capgo Security for the product workflow in Capgo Security, Capgo Trust Center for the product workflow in Capgo Trust Center, and Organization Security for the implementation detail in Organization Security.