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

Le système d'encryption de Capgo utilise des méthodes cryptographiques industrielles pour protéger vos bundles contre tout accès non autorisé. Lorsque l'encryption est activé, vos bundles sont chiffrés avant de quitter votre environnement de développement et restent chiffrés jusqu'à ce qu'ils soient déchiffrés par votre application sur le dispositif de l'utilisateur.

Quel est réellement protégé par l'encryption: À la différence des systèmes OTA qui ne signent que les mises à jour, Capgo chiffre le bundle téléchargé avant stockage et livraison. Cela protège les contenus du bundle contre tout accès non autorisé en stockage ou en transit et garantit que seuls les détenteurs de votre clé privée peuvent produire une mise à jour chiffrée valide. Cela ne ne fait pas les actifs web expédiés impossibles à démonter : la clé publique utilisée par le client pour déchiffrer les mises à jour est distribuée dans l'application, donc un attaquant déterminé peut toujours l'extraire et inspecter les contenus du bundle avec suffisamment d'effort.

Lorsque vous avez besoin d'encryption

Si vous téléchargez un bundle sans encryption, traitez-le comme un actif public. Les canaux privés limitent les appareils qui reçoivent une mise à jour, mais ils ne rendent pas le bundle téléchargé confidentiel. L'encryption est utile lorsque vous voulez une meilleure protection en stockage et en transit et lorsque vous voulez que seuls les détenteurs de la clé privée puissent publier des mises à jour chiffrées valides. Cela ne garantit pas que les JavaScript, HTML ou CSS expédiés ne peuvent jamais être inspectés.

Modèle de menace

La Capgo cryptage protège contre la divulgation du contenu du bundle par Capgo, les fournisseurs de stockage, les CDNs ou toute personne qui ne voit que l'artefact de livraison crypté. Il empêche également les tiers de générer des mises à jour cryptées valides sans votre clé privée. Puisque la clé publique est intégrée dans l'application distribuée, le client peut déchiffrer les mises à jour, mais quelqu'un qui a votre fichier binaire et suffisamment de motivation peut toujours récupérer les informations de clé nécessaires pour inspecter le bundle.

Conseil

La cryptage est particulièrement importante pour :

• Les applications gérant des données sensibles ou des logiques métier
• Les applications d'entreprise avec des exigences de conformité
• Applications déployées dans les secteurs réglementés
• Les organisations avec des politiques de sécurité strictes

Comment fonctionne la cryptage

Capgo utilise une approche d'encryption hybride qui combine l'encryption RSA et AES pour une sécurité et une performance optimales :

1. Génération de Clés

• Clé Privée: Générée et stockée de manière sécurisée dans votre environnement de développement (utilisée pour l'encryption)
• Clé Publique: Dérivée de votre clé privée et stockée dans la configuration de votre application Capacitor (utilisée pour la décryptage)
• Clés de Session: Clés AES aléatoires générées pour chaque téléchargement de bundle

2. Processus d'Encryption

1. Une clé de session AES aléatoire est générée pour chaque téléchargement de bundle
2. Votre bundle est chiffré à l'aide de la clé de session AES
3. Le checksum du bundle est calculé
4. Les deux clés de session AES et le checksum sont chiffrés ensemble à l'aide de votre clé privée RSA (créant la « signature »)
5. Le bundle chiffré et la signature chiffrée sont stockés

Le checksum est chiffré en même temps que la clé AES pour prévenir tout changement. Puisque seuls votre clé privée RSA peut créer cette signature, et uniquement la clé publique correspondante peut la déchiffrer, cela garantit que les deux clés de session AES et le checksum attendu sont authentiques et n'ont pas été modifiés par un attaquant.

3. Processus de déchiffrement

1. Votre application télécharge le bundle chiffré et la signature chiffrée
2. Le Capgo SDK utilise votre clé publique RSA (stockée dans l'application) pour déchiffrer la signature
3. Cela révèle la clé de session AES et le checksum original
4. La clé de session AES est utilisée pour déchiffrer le bundle
5. Un checksum du bundle déchiffré est calculé et comparé avec le checksum original pour vérification d'intégrité

Ce processus garantit que même si un attaquant intercepte le bundle chiffré, il ne peut pas modifier la clé de session AES ou fournir un checksum fictif, car il aurait besoin de votre clé privée pour créer une signature valide que la clé publique peut déchiffrer.

Conseil

Le RSA ne peut chiffrer de grandes quantités de données de manière efficace, il est donc utilisé AES pour le chiffrement réel du paquet tandis que le RSA sécurise la clé AES et fournit une vérification d'intégrité à travers la signature de checksum.

Capgo vs Other Platforms

Fonctionnalité	Capgo	Autres plateformes OTA
Contenu du Paquet	Chiffré en stockage/transport ; toujours inspectable par un ingénieur reverse qui a déterminé l'application binaire	Lisible par le public
Méthode de Sécurité	Chiffrement complet et sécurisé	Code signature uniquement
Niveau de confidentialité	Protection solide de la livraison/stockage; pas de protection contre la décompilation.	La plateforme peut accéder à votre code
Protection	Contenu + intégrité + authenticité	Intégrité + authenticité uniquement

Pourquoi cela compte :

• Code signature seulement vérifie que les mises à jour n'ont pas été altérées et proviennent de la bonne source
• Capgo chiffrement Protège le bundle tant qu'il est stocké et livré et rend les mises à jour chiffrées contrefaites beaucoup plus difficiles car l'attaquant aurait besoin de votre clé privée.
• La reverse engineering est toujours possible après l'expédition de l'application, car le client contient la clé publique nécessaire pour déchiffrer et charger la mise à jour

Méthodes de chiffrement

Capgo utilise le chiffrement V2 comme méthode de chiffrement standard :

Méthode de chiffrement V2 (Norme actuelle)

• Utilise RSA-4096 pour une sécurité renforcée
• Utilise AES-256-GCM pour un chiffrement authentifié
• Fournit une vérification d'intégrité
• Meilleure performance et sécurité

Chiffrement V1 (Déprécié)

• Utilise RSA-2048 pour le chiffrement des clés
• AES-256-CBC pour le chiffrement des ensembles
• Plus disponible actuellement dans le CLI
• Legacy apps using V1 must migrate to V2

Danger

Le chiffrement V1 n'est plus pris en charge actuellement dans le Capgo CLI. Si vous utilisez le chiffrement V1, vous devez migrer vers V2. Voir le guide de migration pour des instructions détaillées.

Configuration du Chiffrement

Étape 1 : Générez des clés d'encryption

Tout d'abord, générer vos clés d'encryption à l'aide du Capgo CLI.

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

Cela crée :

• .capgo_key_v2: Votre clé privée (gardez-la sécurisée !)
• .capgo_key_v2.pub: Votre clé publique (utilisée par votre application)

Ces fichiers sont créés dans le répertoire courant où vous exécutez la commande.

Attention

Notes de stockage importants :

• Clé privée (.capgo_key_v2)Ne jamais commettez cela dans le contrôle de version. Ce fichier doit être conservé confidentiel et utilisé uniquement pour l'encryption lors des téléchargements de bundles.
• Clé publique (.capgo_key_v2.pub): Cela est sécurisé pour être ajouté à la contrôle de version car c'est une copie de votre clé publique.
• Emplacement du fichier: Les clés sont créées dans le répertoire actuel où vous exécutez le key create command.
• : Vous devez exécuter Vous devez lancer key save stockez la clé publique dans votre Capacitor config pour que l'application mobile puisse l'utiliser.

En production, stockez la clé privée de manière sécurisée (variables d'environnement, services de gestion de clés) et supprimez-la de votre projet local après la configuration.

Étape 2 : Sauvegardez votre clé publique dans la Capacitor configuration (obligatoire)

You Terminal Enregistrez votre clé publique dans la Capacitor config afin que votre application mobile puisse déchiffrer les 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"

Étape 3 : Synchronisez votre plateforme Capacitor (obligatoire)

Après avoir enregistré la clé publique, vous Terminal syncronisez le Capacitor plateforme pour copier la configuration mise à jour vers la couche native :

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

Attention

Étapes requises:

1. Le key save La commande stocke la clé publique dans votre Capacitor configuration
2. npx cap sync Cette configuration est copiée vers la couche native où l'application mobile peut y accéder
3. Sans les deux étapes, votre application ne pourra pas déchiffrer les mises à jour chiffrées

Fichiers encapsulés

Méthode 1 : Chiffrer lors de l'envoi

La méthode la plus simple consiste à chiffrer pendant le processus d'envoi :

# Upload with automatic encryption
npx @capgo/cli@latest bundle upload --key-v2

# For external storage, you must encrypt first (see Manual Encryption Workflow below)

Méthode 2 : Flux de travail de chiffrage manuel

Pour plus de contrôle, vous pouvez chiffrer manuellement les bundles :

1. Créer un ensemble zip :

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

2. Chiffrer l'ensemble :

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

3. Téléchargez votre stockage (par exemple, S3) et enregistrez avec 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

Gestion des clés

Stockage des clés de manière sécurisée

Options de clé privée :

1. Fichier local (développement local) :

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

2. Variable d'environnement (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"

Configuration de la clé publique (obligatoire) :

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

Environnement de production :

• Stockez les clés privées dans des services de gestion de clés sécurisés (AWS KMS, Azure Key Vault, etc.)
• Utilisez la gestion des secrets CI/CD pour les clés privées
• N'ajoutez jamais les clés privées au contrôle de version

Key Usage:

• Clé privée: Utilisé par CLI pour la cryptage lors de l'envoi du bundle (gardez sécurisé)
• Clé publique: Stored in app configuration for decryption on device (safe to commit)

Rotation après une compromission de la clé privée

Rotation du couple de clés lorsque la clé privée est soupçonnée ou confirmée compromise. Une rotation calendaire régulière n'est pas requise. Il s'agit d'une migration de clé native, pas d'une modification OTA uniquement.

1. Générez un nouveau couple de clés :

   npx @capgo/cli@latest key create

2. Sauvegardez la nouvelle clé publique dans la configuration de Capacitor :

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

3. Sync et expédiez une version native : Exécuter npx cap syncEnsuite, distribuez une nouvelle version native de l'application contenant la nouvelle clé publique de remplacement.

4. La ciblage de version Les appareils qui exécutent toujours le code natif ancien ne peuvent pas déchiffrer les mises à jour chiffrées avec la nouvelle clé de remplacement. Utilisez Changer votre secret d'upload : Restreindre les ensembles de clés de remplacement aux nouvelles versions natives tout en laissant le reste de la flotte se mettre à jour via l'App Store ou MDM.

5. Changer votre secret d'upload : 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.

Pratiques de Sécurité Avancées

Sécurité Clé

• N'envoyez jamais les clés privées entre environnements ou membres d'équipe
• Utilisez des clés différentes pour différents environnements (dev, étape, production)
• Rotafter une compromission: remplacez le paire de clés lorsque la clé privée est suspectée ou confirmée compromise ; une rotation régulière du calendrier n'est pas requise
• Stockez les clés de manière sécurisée utiliser des systèmes de gestion des clés appropriés

Sécurité du Bundle

• Vérifiez toujours l'intégrité du bundle après décryptage
• Surveillez les modèles de téléchargement inhabituels ou les échecs
• Utilisez HTTPS for all bundle URLs (required for mobile apps)
• Implémentez Gestion des erreurs appropriée pour les échecs de déchiffrement

Contrôle d'accès

• Restreindre l'accès à des clés d'encryption uniquement aux personnels autorisés
• Utiliser l'accès basé sur le rôle pour les opérations de gestion de clés
• Audit l'utilisation et l'accès des clés régulièrement
• Mettre en œuvre procedures de sauvegarde et de récupération appropriées

Résolution des problèmes d'encryption

Problèmes courants

Échecs de déchiffrement :

• Vérifiez que la clé privée correspond à la clé publique utilisée pour l'encryption
• Vérifiez que le ivSessionKey est correct
• Assurez-vous d'utiliser la cryptage V2 (V1 n'est plus pris en charge)

Erreurs liées aux clés :

• Confirmez que le format de la clé privée est correct (format PEM)
• Vérifiez que la clé n'a pas été corrompue lors de son stockage/transfer
• Vérifiez que la clé a les permissions appropriées dans votre configuration d'application

Problèmes de performance :

• Large bundles may take longer to encrypt/decrypt
• Utilisez les mises à jour Delta pour réduire les tailles des bundles
• Surveiller les performances du dispositif pendant la décryptage

Commandes de débogage

Vérifiez l'état de l'encryption :

npx @capgo/cli@latest app debug

Tester le flux de workflow d'encryption/décryption :

# 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

Conformité et normes

L'implémentation d'Capgo de chiffrement respecte les normes de l'industrie :

• AES-256: Algorithme d'encryption approuvé FIPS 140-2
• RSA-4096: Forte encryption asymétrique pour la protection des clés
• Mode GCM: fournit à la fois la confidentialité et l'authenticité
• Aléatoire Sûr: Génération de nombres aléatoires cryptographiquement sûrs

Cela rend Capgo adapté aux applications nécessitant le respect de :

• Règlement général sur la protection des données (RGPD)
• Loi de portabilité et de responsabilité dans l'assurance maladie (HIPAA)
• Contrôle de service organisation 2 (SOC 2)
• ISO 27001 (Gestion de la sécurité des informations)

Considérations relatives à la performance

Surcharge de chiffrement

• Taille du paquetTaille des paquets chiffrés est légèrement supérieure (~1-2% de surcharge)
• Temps de traitementL'encryption/désactivation ajoute une latence minimale
• Utilisation de la mémoire: Augmentation temporaire pendant les opérations d'encryption/décryptage

Conseils d'optimisation

• Use Delta updates to minimize encrypted data transfer
• Optimisez la taille de votre bundle en convertissant les images au format WebP
• Minimisez les fichiers JavaScript et CSS avant la mise en bundle
• Supprimez les dépendances inutilisées et code
• Monitor device performance on older/slower devices

Étapes suivantes

• Apprenez à Stockage personnalisé pour utiliser la chiffrage avec votre propre infrastructure
• Découvrez Canaux gestionner des ensembles chiffrés à travers les environnements
• Configurer Intégration CI/CD pour automatiser les déploiements chiffrés

Continuez de la section Chiffrement

Si vous utilisez Encryption planifier la sécurité et la conformité, connectez-l’à Compliance pour les détails d'implémentation dans la Compliance, Capgo Sécurité Scanner pour le flux de travail du produit dans Capgo Sécurité Scanner, Capgo Sécurité pour le flux de travail du produit dans Capgo Sécurité, Capgo Centre de confiance pour le flux de travail du produit dans Capgo Centre de confiance, et Sécurité de l'organisation pour le détail d'implémentation dans Sécurité de l'organisation.