콘텐츠로 건너뛰기

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:

Capgo Encryption Flow

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.

Capgo vs Other Platforms

FeatureCapgoOther OTA Platforms
Bundle ContentFully encrypted (unreadable)Publicly readable
Security MethodTrue end-to-end encryptionCode signing only
Privacy LevelZero-knowledge (even Capgo can’t read your code)Platform can access your code
ProtectionContent + integrity + authenticityIntegrity + 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:

Terminal window
# 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:

Terminal window
# 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:

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

Encrypting Bundles

Method 1: Encrypt During Upload

The simplest way is to encrypt during the upload process:

Terminal window
# 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:

    Terminal window
    npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2
  2. Encrypt the bundle:

    Terminal window
    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:

    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 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):

    Terminal window
    # Key stored as .capgo_key_v2 file in project root
    npx @capgo/cli@latest bundle upload --key-v2
  2. Environment variable (CI/CD):

    Terminal window
    # 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):

Terminal window
# 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:

    Terminal window
    # 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:

    Terminal window
    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:

Terminal window
npx @capgo/cli@latest app debug

Test encryption/decryption workflow:

Terminal window
# 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