Chiffrement

Capgo provides robust end-to-end Chiffrement for your Application Bundles, ensuring that your JavaScript code and assets are protected during transmission and storage. This Chiffrement system is designed to give you Terminé control over your Application’s Sécurité while maintaining the convenience of Mises à jour en direct.

Aperçu

Capgo’s Chiffrement system uses industry-standard cryptographic methods to protect your Bundles from unauthorized access. When Chiffrement is enabled, your Bundles are Chiffré before leaving your Développement environment and remain Chiffré until they’re decrypted by your Application on the Utilisateur’s Appareil.

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.

Astuce

Chiffrement is particularly Important for:

• Apps handling sensitive data or business logic
• Entreprise applications with compliance requirements
• Apps deployed in regulated industries
• Organizations with strict Sécurité policies

How Chiffrement Works

Capgo uses a hybrid Chiffrement approach that combines RSA and AES Chiffrement for optimal Sécurité and performance:

1. Key Generation

• Private Key: Generated and stored securely in your Développement environment (used for Chiffrement)
• Public Key: Derived from your private key and stored in your Application’s Capacitor config (used for decryption)
• Session Keys: Random AES keys generated for each Bundle Télécharger

2. Chiffrement Process

1. A random AES session key is generated for each Bundle Télécharger
2. Your Bundle is Chiffré using the AES session key
3. The Bundle checksum is calculated
4. Both the AES session key and checksum are Chiffré together using your RSA private key (creating the “signature”)
5. The Chiffré Bundle and Chiffré signature are stored

The checksum is Chiffré alongside the AES key to prevent tampering. Since only your RSA private key can Créer 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 Application downloads the Chiffré Bundle and Chiffré signature
2. The Capgo SDK uses your RSA public key (stored in the Application) 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 Chiffré Bundle, they cannot modify the AES session key or provide a fake checksum, because they would need your private key to Créer a valid signature that the public key can decrypt.

Astuce

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

Capgo vs Other Platforms

Fonctionnalité	Capgo	Other OTA Platforms
Bundle Content	Fully Chiffré (unreadable)	Publicly readable
Sécurité Method	True end-to-end Chiffrement	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 Mises à jour haven’t been tampered with and come from the right source
• End-to-end Chiffrement ensures that your actual code content remains private and unreadable during transmission and storage
• With Capgo’s true end-to-end Chiffrement, only your Utilisateurs can decrypt Mises à jour - no one else, including Capgo itself

Chiffrement Methods

Capgo uses Chiffrement V2 as the standard Chiffrement method:

Chiffrement V2 (Current Standard)

• Uses RSA-4096 for enhanced Sécurité
• AES-256-GCM for authenticated Chiffrement
• Provides integrity verification
• Better performance and Sécurité

Chiffrement V1 (Obsolète)

• Uses RSA-2048 for key Chiffrement
• AES-256-CBC for Bundle Chiffrement
• No longer Disponible in the current CLI
• Legacy apps using V1 must Migrer to V2

Danger

Chiffrement V1 is no longer supported in the current Capgo CLI. If you’re using V1 Chiffrement, you must Migrer to V2. See the [Migration Guide](/docs/Mise à niveau/Chiffrement-v1-to-v2/) for detailed instructions.

Setting Up Chiffrement

Step 1: Generate Chiffrement Keys

First, generate your Chiffrement 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 Commande.

Attention

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 Retirer it from your local project after Configuration.

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

You must Enregistrer your public key to the Capacitor config so your mobile Application 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: Synchroniser Capacitor Platform (Required)

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

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

Attention

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 Application won’t be able to decrypt Chiffré Mises à jour

Encrypting Bundles

Method 1: Encrypt During Télécharger

The simplest way is to encrypt during the Télécharger 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 Chiffrement Workflow

For more control, you can manually encrypt Bundles:

1. Créer 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. Télécharger 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 Développement):

   # 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 Chiffrement during Bundle Télécharger (keep secure)
• Public Key: Stored in Application Configuration for decryption on Appareil (safe to commit)

Key Rotation

Regularly rotate your Chiffrement keys for enhanced Sécurité:

1. Generate Nouveau keys:

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

2. Enregistrer the Nouveau public key to Capacitor config:

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

3. Mise à jour your Application Configuration with the Nouveau public key

4. Déployer the updated Application before uploading Chiffré Bundles with the Nouveau key

Sécurité Best Practices

Key Sécurité

• Never share private keys between environments or team Membres
• 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 Sécurité

• Always verify Bundle integrity after decryption
• Monitor for unusual Télécharger patterns or failures
• Use HTTPS for all Bundle URLs (required for mobile apps)
• Implement proper Erreur handling for decryption failures

Access Control

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

Dépannage Chiffrement

Problèmes courants

Decryption failures:

• Verify the private key matches the public key used for Chiffrement
• Check that the ivSessionKey is correct
• Ensure you’re using Chiffrement 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
• Vérifier that the key has proper permissions in your Application Configuration

Performance issues:

• Large Bundles may take longer to encrypt/decrypt
• Consider using differential Mises à jour to reduce Bundle sizes
• Monitor Appareil performance during decryption

Débogage Commandes

Vérifier Chiffrement status:

npx @capgo/cli@latest app debug

Test Chiffrement/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 Chiffrement implementation follows industry standards:

• AES-256: FIPS 140-2 approved Chiffrement algorithm
• RSA-4096: Strong asymmetric Chiffrement 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 Organisation Control 2)
• ISO 27001 (Information Sécurité Management)

Performance Considerations

Chiffrement Overhead

• Bundle size: Chiffré Bundles are slightly larger (~1-2% overhead)
• Processing time: Chiffrement/decryption adds minimal latency
• Memory Utilisation: Temporary increase during Chiffrement/decryption operations

Optimization Tips

• Use differential Mises à jour to minimize Chiffré data transfer
• Optimize your Bundle size by converting images to WebP format
• Minimize JavaScript and CSS files before bundling
• Retirer unused dependencies and code
• Monitor Appareil performance on older/slower Appareils

Suivant Steps

• Learn À propos [Custom Storage](/docs/live-Mises à jour/custom-storage/) to use Chiffrement with your own infrastructure
• Explore [Canaux](/docs/live-Mises à jour/Canaux/) to manage Chiffré Bundles across environments
• Set up CI/CD Integration to automate Chiffré deployments