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.
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
- A random AES session key is generated for each bundle upload
- Your bundle is encrypted using the AES session key
- The bundle checksum is calculated
- Both the AES session key and checksum are encrypted together using your RSA private key (creating the “signature”)
- 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
- Your app downloads the encrypted bundle and encrypted signature
- The Capgo SDK uses your RSA public key (stored in the app) to decrypt the signature
- This reveals the AES session key and the original checksum
- The AES session key is used to decrypt the bundle
- 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.
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
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.
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 directlynpx @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 nativenpx cap sync
Encrypting Bundles
Method 1: Encrypt During Upload
The simplest way is to encrypt during the upload process:
# Upload with automatic encryptionnpx @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:
-
Create a zip bundle:
Terminal window npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2 -
Encrypt the bundle:
Terminal window npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM_FROM_STEP_1 -
Upload to your storage (e.g., S3) and register with Capgo:
Terminal window # 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 URLnpx @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:
-
File-based (local development):
Terminal window # Key stored as .capgo_key_v2 file in project rootnpx @capgo/cli@latest bundle upload --key-v2 -
Environment variable (CI/CD):
Terminal window # Store in environment variable for CIexport 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 appnpx @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:
-
Generate new keys:
Terminal window # Navigate to desired directory first, then create keysmkdir ./new-keys && cd ./new-keysnpx @capgo/cli@latest key create -
Save the new public key to Capacitor config:
Terminal window npx @capgo/cli@latest key save --key ./new-keys/.capgo_key_v2.pub -
Update your app configuration with the new public key
-
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 → unzipnpx @capgo/cli@latest bundle zip com.example.app --key-v2npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM --jsonnpx @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