Chiffrement

Capgo offre un chiffrement de bout en bout robuste pour vos bundles d'application, garantissant que votre code JavaScript et vos assets sont protégés pendant la transmission et le stockage. Ce système de chiffrement est conçu pour vous donner un contrôle total sur la sécurité de votre application tout en conservant la simplicité des live updates.

Aperçu

Le système de chiffrement de Capgo utilise des méthodes cryptographiques standards de l'industrie pour protéger vos bundles contre tout accès non autorisé. Lorsque le chiffrement 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 l'appareil de l'utilisateur.

Ce que le chiffrement protège réellement: Contrairement aux systèmes OTA qui se contentent de signer les mises à jour, Capgo chiffre le bundle envoyé avant son stockage et sa distribution. Cela protège le contenu du bundle contre un accès accidentel lors du stockage ou du transit, et garantit que seul un détenteur de votre clé privée peut produire une mise à jour chiffrée valide. Cela ne pas rend pas les assets web livrés impossibles à rétro-concevoir : la clé publique utilisée par le client pour déchiffrer les mises à jour est distribuée dans l'application ; un attaquant déterminé peut donc toujours l'extraire et inspecter le contenu du bundle avec suffisamment d'efforts.

Quand utiliser le chiffrement

Si vous envoyez un bundle sans chiffrement, considérez-le comme un asset public. Les canaux privés limitent les appareils qui reçoivent une mise à jour, mais ils ne rendent pas le bundle envoyé confidentiel. Le chiffrement est utile pour obtenir une meilleure protection au stockage et au transit, et pour garantir que seuls les détenteurs de la clé privée puissent publier des mises à jour chiffrées valides. Il ne garantit pas que le JavaScript, le HTML ou le CSS livrés ne pourront jamais être inspectés.

Modèle de menace

Le chiffrement Capgo protège contre la divulgation du bundle par Capgo, les fournisseurs de stockage, les CDN ou toute personne ne voyant que l'artefact de livraison chiffré. Il empêche également des tiers de générer des mises à jour chiffrées valides sans votre clé privée. Comme la clé publique est intégrée à l'application distribuée pour permettre au client de déchiffrer les mises à jour, une personne possédant votre binaire d'application et suffisamment motivée peut toujours récupérer les éléments de clé nécessaires pour inspecter le bundle.

Astuce

Le chiffrement est particulièrement important pour :

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

Modèle de sécurité

Confidentialité vis-à-vis de Capgo

Votre clé privée RSA est générée et conservée sur votre machine. Le CLI de Capgo ne transmet jamais votre clé privée, et Capgo ne la stocke pas. Capgo ne stocke pas non plus votre clé publique RSA complète : les uploads incluent seulement un court key_id (les 20 premiers caractères du corps PEM) afin que les canaux puissent correspondre à la paire de clés utilisée.

Les bundles complets chiffrés sont stockés et livrés sous forme de texte chiffré AES-128-CBC. Les services Capgo, le CDN, le stockage objet et quiconque sur le chemin de livraison ne voit que les artefacts hébergés ne peuvent pas lire votre JavaScript, votre HTML ou vos assets sans votre clé privée.

Confidentialité maximale de Capgo

Par défaut, le chiffrement rend déjà le contenu confidentiel dans le stockage Capgo et en transit. Si vous voulez aussi réduire ce que Capgo pourrait apprendre en liant votre canal de mise à jour à un binaire de store donné, suivez le guide ci-dessous.

Utilisez un app ID Capgo dédié. Définissez plugins.CapacitorUpdater.appId (votre Capgo app_id) à une valeur qui est pas la même que votre bundle ID iOS ou votre application ID Android. Les builds Store et MDM intègrent votre clé publique RSA dans capacitor.config. Lorsque le Capgo app_id correspond au nom du package du store, il est plus facile d'associer l'application Capgo à un binaire publié contenant cette clé publique. Un app ID Capgo distinct évite ce lien direct.

Capgo Builder et la clé publique. Les uploads de Capgo Builder zippent votre projet avec capacitor.config (et l'arborescence native), incluant plugins.CapacitorUpdater.publicKey après key save. Pour ne pas inclure la clé publique dans les uploads de Builder :

• Compilez vos apps natives localement ou via votre propre CI lorsque la confidentialité vis-à-vis de Capgo est importante, et évitez d'envoyer ces arborescences via Capgo Builder tant que la clé publique est dans la config, ou
• Ajoutez la clé publique avec key save uniquement après la fin de tout upload de Builder qui ne doit pas exposer la clé, ou
• Si vous utilisez Capgo Builder pour vos builds natifs, considérez ce workflow comme garantissant une forte intégrité (checksums signés) mais ne pas présumez pas de la confidentialité de Capgo une fois la clé publique incluse dans un upload de Builder.

Chiffrez les uploads de deltas. Le contenu des fichiers delta (partiels) est en clair, sauf si vous utilisez @capgo/capacitor-updater la version 6.14.4 ou plus récente (le chiffrement partiel est activé par défaut pour les uploads chiffrés sur les versions d'updater compatibles) ou passez --encrypt-partial sur bundle upload. Même avec un chiffrement partiel, noms de fichiers listés dans les manifestes delta ne sont pas chiffrés ; seuls les hashs par fichier sont protégés par RSA.

Intégrité

Après le déchiffrement, l'updater calcule le SHA-256 du bundle et le compare au checksum récupéré de la signature protégée par RSA. En cas de discordance, le bundle est supprimé et n'est jamais activé :

• Android vérifie le checksum après le déchiffrement et avant l'extraction de l'archive.
• iOS déchiffre et extrait d'abord, puis vérifie le checksum avant le bundle peut être activé.

Lorsqu'une clé publique est configurée, les checksums manquants ou non signés par RSA sont rejetés.

Gestion des clés

Pour chaque upload de zip complet, le CLI génère un nouveau AES-128 clé de session et IV de 16 octets, chiffre le bundle avec AES-128-CBC, et chiffre la clé de session avec votre RSA-2048 clé privée via le padding de type PKCS#1 v1.5. Les appareils récupèrent la clé AES grâce à la clé publique RSA intégrée à l'app. Les clés et IV ne sont pas réutilisés entre deux uploads de bundles CLI distincts. Lors d'un upload delta, tous les fichiers partiels chiffrés partagent la clé de session et l'IV de cet upload.

La clé publique utilisée pour le déchiffrement est intégrée à votre app publiée. Le contenu en clair du bundle est accessible sur les appareils exécutant votre app via le même chemin de déchiffrement que l'updater, de manière comparable aux autres assets du package de l'app.

Échecs et reporting

Les échecs de décryptage et de checksum sont signalés comme des événements de stats ("download_fail, checksum_fail, decrypt_fail) vers l'endpoint de stats Capgo ou votre gestionnaire de stats auto-hébergé. Les stats sont envoyées depuis l'appareil ; rien n'est rapporté aux hébergeurs de bundles tiers en fonction du succès ou de l'échec du décryptage. Chaque tentative est généralement un téléchargement complet initié par l'appareil, ce qui rend les sondages de type padding-oracle peu pratiques, et un texte clair modifié échouera toujours au checksum signé.

Durcissement futur

Une future version majeure pourrait ajouter un format versionné avec AES-GCM et RSA-PSS sur le hash comme défense en profondeur, en complément de la conception actuelle. Il s'agirait d'une étape de renforcement progressive, et non d'un correctif de sécurité d'urgence pour le format actuel.

Fonctionnement du chiffrement

Capgo utilise une approche de chiffrement hybride combinant le chiffrement RSA et AES pour une sécurité et des performances optimales :

1. Génération de la clé

• Clé privée: Généré et stocké de manière sécurisée dans votre environnement de développement (utilisé pour le chiffrement)
• Clé publique: Dérivée de votre clé privée et stockée dans la config Capacitor de votre app (utilisée pour le déchiffrement)
• Clés de session: Clés AES aléatoires générées pour chaque upload de bundle

2. Processus de chiffrement

1. Une clé de session AES aléatoire est générée pour chaque upload de bundle
2. Votre bundle est chiffré avec la clé de session AES
3. Le checksum du bundle est calculé
4. La clé de session AES et le checksum sont chiffrés ensemble via votre clé privée RSA (créant ainsi la « signature »)
5. Le bundle chiffré et la signature chiffrée sont stockés

Le checksum est chiffré avec la clé AES pour empêcher toute falsification. Comme seule votre clé privée RSA peut créer cette signature, et que seule la clé publique correspondante peut la déchiffrer, cela garantit que la clé 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'app) pour déchiffrer la signature
3. Cela révèle la clé de session AES et le checksum d'origine
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é au checksum d'origine pour vérifier l'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 ni fournir un faux checksum, car il aurait besoin de votre clé privée pour créer une signature valide que la clé publique peut déchiffrer.

Astuce

RSA ne peut pas chiffrer efficacement de grandes quantités de données ; AES est donc utilisé pour le chiffrement réel du bundle, tandis que RSA sécurise la clé AES et assure la vérification de l'intégrité via la signature du checksum.

Capgo vs les autres plateformes

Fonctionnalité	Capgo	Autres plateformes OTA
Contenu du bundle	Chiffré au repos/en transit ; reste inspectable par un reverse engineer déterminé avec le binaire de l’app	Lisible publiquement
Méthode de sécurité	Chiffrement de bout en bout réel	Signature Code uniquement
Niveau de confidentialité	Protection forte de la livraison/stockage ; pas d'anti-reverse-engineering	La plateforme peut accéder à votre code
Protection	Contenu + intégrité + authenticité	Intégrité + authenticité uniquement

Pourquoi c'est important :

• Signature Code vérifie seulement que les mises à jour n'ont pas été altérées et proviennent de la bonne source
• Chiffrement Capgo protège le bundle pendant son stockage et sa livraison, rendant la falsification de mises à jour chiffrées bien plus difficile car l'attaquant aurait besoin de votre clé privée
• L'ingénierie inverse reste possible après la publication de l'app, car le client contient la clé publique nécessaire pour déchiffrer et charger la mise à jour

Méthodes de chiffrement

Capgo utilise l'Encryption V2 comme méthode de chiffrement standard :

Chiffrement V2 (standard actuel)

• Utilise RSA-4096 pour une sécurité renforcée
• AES-256-GCM pour un chiffrement authentifié
• Assure la vérification de l'intégrité
• Meilleures performances et sécurité

Chiffrement V1 (obsolète)

• Utilise RSA-2048 pour le chiffrement des clés
• AES-256-CBC pour le chiffrement du bundle
• N'est plus disponible dans la version actuelle de CLI
• Legacy apps using V1 must migrate to V2

Danger

L'encryption V1 n'est plus prise en charge dans l'actuel Capgo CLI. Si vous utilisez l'encryption V1, vous devez migrer vers la V2. Consultez la guide de migration pour des instructions détaillées.

Configuration du chiffrement

Étape 1 : Générer les clés de chiffrement

Tout d'abord, générez vos clés de chiffrement en utilisant la 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-l’en sécurité !)
• .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 importantes sur le stockage :

• Clé privée (.capgo_key_v2)Ne commitez jamais ce fichier au contrôle de version. Il doit rester sécurisé et ne servir qu'au chiffrement lors de l'upload de vos bundles.
• Clé publique (.capgo_key_v2.pub): Vous pouvez commiter ce fichier en toute sécurité, car il s'agit d'une sauvegarde de votre clé publique.
• Emplacement du fichier: Les clés sont créées dans le répertoire courant où vous exécutez la key create commande.
• Clé publique dans la config: Vous devez exécuter key save pour stocker la clé publique dans votre config Capacitor afin que l'application mobile puisse l'utiliser.

Pour une utilisation 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 : Enregistrer votre clé publique dans la config Capacitor (requis)

Vous devez enregistrez votre clé publique dans la config Capacitor pour 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 : Synchroniser la plateforme Capacitor (requis)

Après avoir enregistré la clé publique, vous devez synchronisez la plateforme Capacitor pour copier la config 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 enregistre la clé publique dans votre config Capacitor
2. npx cap sync copie cette config vers la couche native pour que l'app mobile puisse y accéder
3. Sans ces deux étapes, votre app ne pourra pas décrypter les mises à jour chiffrées

Chiffrer les bundles

Méthode 1 : Chiffrer lors de l'upload

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

# 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 : Workflow de chiffrement manuel

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

1. Créer un bundle zip :

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

2. Chiffrer le bundle :

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

3. Envoyez vers votre stockage (par ex. 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

Stocker les clés en toute sécurité

Options de clé privée :

1. Via un fichier (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
• Ne commitez jamais de clés privées dans votre version control

Usage de la clé :

• Clé privée: Utilisée par CLI pour le chiffrement lors de l'upload du bundle (à garder secrète)
• Clé publique: Stockée dans la configuration de l'app pour le déchiffrement sur l'appareil (peut être commitée)

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

Remplacez la paire de clés en cas de suspicion ou de confirmation de compromission de la clé privée. Une rotation calendaire régulière n'est pas nécessaire. Il s'agit d'une migration de clé native, pas d'un simple changement OTA.

1. Générez une nouvelle paire de clés :

   npx @capgo/cli@latest key create

2. Enregistrez la nouvelle clé publique dans votre config Capacitor :

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

3. Synchronisez et déployez une release native : Exécutez npx cap sync, puis distribuez une nouvelle version de l'app native contenant la nouvelle clé publique.

4. Ciblez la nouvelle version native : Les appareils utilisant encore l'ancien binaire natif ne pourront pas décrypter les mises à jour chiffrées avec la nouvelle clé. Utilisez Ciblage de version pour restreindre les bundles avec la nouvelle clé à la nouvelle version native, pendant que le reste du parc se met à jour via le store ou un MDM.

5. Changez votre secret d'upload : Dès que cette release native est en ligne, remplacez la clé privée dans votre CI et n'envoyez que les bundles ciblant les versions natives contenant la nouvelle clé publique.

Attention

Si la clé privée est compromise, cessez immédiatement de l'utiliser. Les installations existantes utilisant l'ancienne clé publique nécessiteront une mise à jour via le store natif ou un MDM avant de pouvoir recevoir des bundles chiffrés avec la nouvelle clé.

Bonnes pratiques de sécurité

Sécurité des clés

• Ne partagez jamais vos clés privées entre les environnements ou les membres de l'équipe
• Utilisez des clés différentes pour chaque environnement (dev, staging, production)
• Effectuez une rotation après une compromission: remplacez la paire de clés si la clé privée est suspectée ou confirmée compromise ; une rotation calendaire de routine n'est pas requise
• Stockez les clés de manière sécurisée using proper key management systems

Sécurité du bundle

• Toujours vérifier l'intégrité du bundle après le décryptage
• Surveiller les échecs ou les schémas de téléchargement inhabituels
• Utiliser HTTPS pour toutes les URL de bundle (requis pour les apps mobiles)
• Implémenter une gestion d'erreurs adaptée pour les échecs de décryptage

Contrôle d'accès

• Limiter l'accès aux clés de chiffrement au seul personnel autorisé
• Utilisez l'accès basé sur les rôles pour les opérations de gestion des clés
• Auditer l'utilisation et l'accès aux clés régulièrement
• Implémenter procédures de sauvegarde et de récupération appropriées

Dépannage du chiffrement

Problèmes courants

Échecs de déchiffrement :

• Vérifiez que la clé privée correspond à la clé publique utilisée pour le chiffrement
• Vérifiez que le ivSessionKey est correct
• Assurez-vous d’utiliser Encryption V2 (V1 n’est plus prise 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 du stockage ou du transfert
• Vérifiez que la clé possède les bonnes permissions dans la configuration de votre app

Problèmes de performance :

• Large bundles may take longer to encrypt/decrypt
• Pensez à utiliser les Delta updates pour réduire la taille des bundles
• Surveillez les performances de l'appareil pendant le décryptage

Commandes de debug

Vérifier le statut du chiffrement :

npx @capgo/cli@latest app debug

Tester le workflow de chiffrement/décryptage :

# 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 standards

L’implémentation du chiffrement de Capgo respecte les standards de l’industrie :

• AES-256 : algorithme de chiffrement homologué FIPS 140-2
• RSA-4096 : chiffrement asymétrique robuste pour la protection des clés
• Mode GCM : garantit à la fois la confidentialité et l’authenticité
• Random sécurisé : génération de nombres aléatoires cryptographiquement sûre

Cela rend Capgo adapté aux applications exigeant la conformité avec :

• RGPD (Règlement général sur la protection des données)
• la loi HIPAA (Health Insurance Portability and Accountability Act)
• SOC 2 (Service Organization Control 2)
• ISO 27001 (Gestion de la sécurité de l'information)

Considérations de performance

Surcharge liée au chiffrement

• Taille du bundle: Les bundles chiffrés sont légèrement plus volumineux (~1-2 % de surcharge)
• Temps de traitement: Le chiffrement/déchiffrement ajoute une latence minimale
• Utilisation de la mémoire: Augmentation temporaire lors des opérations de chiffrement/déchiffrement

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 le bundling
• Supprimez les dépendances inutilisées et code
• Surveillez les performances sur les appareils plus anciens ou plus lents

Étapes suivantes

• En savoir plus sur Stockage personnalisé pour utiliser le chiffrement avec votre propre infrastructure
• Explorer Canaux pour gérer les bundles chiffrés entre les environnements
• Configurer Intégration CI/CD pour automatiser les déploiements chiffrés

Continuer à partir du chiffrement

Si vous utilisez Chiffrement pour planifier la sécurité et la conformité, connectez-l’à Conformité pour le détail d’implémentation dans Compliance, Scanner de sécurité Capgo pour le workflow produit dans Capgo Security Scanner, Capgo Sécurité pour le workflow produit dans Capgo Security, Capgo Centre de confiance pour le workflow produit dans Capgo Trust Center, et Sécurité de l'organisation pour le détail d'implémentation dans Organization Security.