Crittografia

Capgo offre una crittografia end-to-end robusta per i bundle della tua app, garantendo che il tuo code JavaScript e gli asset siano protetti durante la trasmissione e l'archiviazione. Questo sistema di crittografia è progettato per darti il controllo completo sulla sicurezza della tua app, mantenendo la comodità degli aggiornamenti live.

Panoramica

Il sistema di crittografia di Capgo utilizza metodi crittografici standard del settore per proteggere i tuoi bundle da accessi non autorizzati. Quando la crittografia è attiva, i bundle vengono cifrati prima di lasciare l'ambiente di sviluppo e restano cifrati finché la tua app non li decifra sul dispositivo dell'utente.

Cosa protegge davvero la crittografia: A differenza dei sistemi OTA che si limitano a firmare gli aggiornamenti, Capgo cripta il bundle caricato prima dello storage e della distribuzione. Questo protegge il contenuto del bundle da accessi occasionali durante lo storage o il transito e garantisce che solo chi possiede la tua chiave privata possa generare un aggiornamento criptato valido. Non non rende impossibile il reverse engineering degli asset web distribuiti: la chiave pubblica usata dal client per decriptare gli aggiornamenti è inclusa nell'app, quindi un attaccante determinato può comunque estrarla e ispezionare il contenuto del bundle con sufficiente impegno.

Quando serve la crittografia

Se carichi un bundle senza crittografia, consideralo un asset pubblico. I canali privati limitano quali dispositivi ricevono un aggiornamento, ma non rendono riservato il bundle caricato. La crittografia è utile per una maggiore protezione durante lo storage e il transito e quando vuoi che solo i possessori della chiave privata possano pubblicare aggiornamenti criptati validi. Non garantisce che JavaScript, HTML o CSS distribuiti non possano mai essere ispezionati.

Modello di minaccia

La crittografia di Capgo protegge il bundle dalla divulgazione da parte di Capgo, provider di storage, CDN o chiunque veda solo l'artifact di consegna crittografato. Impedisce inoltre a terzi di generare aggiornamenti crittografati validi senza la tua chiave privata. Poiché la chiave pubblica è integrata nell'app distribuita per permettere al client di decriptare gli aggiornamenti, chi possiede il binario dell'app e ha una motivazione sufficiente potrebbe comunque recuperare il materiale della chiave necessario per ispezionare il bundle.

Tip

La crittografia è particolarmente importante per:

• App che gestiscono dati sensibili o business logic
• Applicazioni enterprise con requisiti di compliance
• App distribuite in settori regolamentati
• Organizzazioni con policy di sicurezza rigorose

Modello di sicurezza

Riservatezza rispetto a Capgo

La tua chiave privata RSA viene generata e conservata sulla tua macchina. Il CLI di Capgo non trasmette mai la tua chiave privata, e Capgo non la memorizza. Anche Capgo non memorizza la tua chiave pubblica RSA completa: gli upload includono solo una breve key_id (i primi 20 caratteri del corpo PEM) in modo che i canali possano corrispondere alla chiave che hai usato.

I bundle completi criptati vengono archiviati e consegnati come testo cifrato AES-128-CBC. I servizi Capgo, la CDN, l'object storage e chiunque nel percorso di consegna veda solo gli artefatti ospitati non può leggere il tuo JavaScript, HTML o gli asset senza la tua chiave privata.

Massima riservatezza con Capgo

La crittografia predefinita mantiene il bundle contenuti riservati nello storage Capgo e durante il transito. Se vuoi anche ridurre ciò che Capgo potrebbe apprendere collegando il tuo canale di update a un particolare binario dello store, segui questa guida.

Usa un app ID Capgo dedicato. Imposta plugins.CapacitorUpdater.appId (il tuo Capgo app_id) a un valore che non lo stesso del tuo bundle ID iOS o dell'application ID Android. Le build Store e MDM incorporano la tua chiave pubblica RSA in capacitor.config. Quando il Capgo app_id corrisponde al nome del pacchetto dello store, è più facile associare l'app Capgo a un binario pubblicato che contiene quella chiave pubblica. Un ID app Capgo separato evita questo collegamento diretto.

Capgo Builder e la chiave pubblica. Gli upload di Capgo Builder zippano il tuo progetto con capacitor.config (e l'albero nativo), inclusi plugins.CapacitorUpdater.publicKey dopo key save. Per evitare che la chiave pubblica finisca negli upload di Builder:

• Esegui la build delle app native localmente o nella tua CI quando la riservatezza rispetto a Capgo è fondamentale, ed evita di caricare quegli alberi tramite Capgo Builder se la chiave pubblica è presente nella config, o
• Aggiungi la chiave pubblica con key save solo dopo che tutti gli upload del Builder che non devono esporre la chiave sono stati completati, o
• Se utilizzi Capgo Builder per i Native Build, considera il workflow come un sistema con forte integrità (checksum firmati) ma non non garantisce la riservatezza di Capgo una volta inclusa la chiave pubblica in un upload del Builder.

Crittografa gli upload delta. I corpi dei file delta (parziali) sono in chiaro a meno che tu non usi @capgo/capacitor-updater la versione 6.14.4 o superiore (la crittografia parziale è abilitata automaticamente per gli upload criptati su versioni updater supportate) o passi --encrypt-partial su bundle upload. Anche con la crittografia parziale, i nomi dei file nei delta manifest non sono criptati; solo gli hash per singolo file sono protetti tramite RSA.

Integrità

Dopo la decrittazione, l'updater calcola il SHA-256 sul bundle e lo confronta con il checksum recuperato dalla firma RSA-wrapped. In caso di mismatch, il bundle viene rimosso e non attivato:

• Android controlla il checksum dopo la decrittazione e prima l'estrazione dell'archivio.
• iOS decripta e scompattata prima, poi verifica il checksum prima il bundle può essere attivato.

Quando è configurata una chiave pubblica, i checksum mancanti o non firmati correttamente con RSA vengono rifiutati.

Gestione delle chiavi

Per ogni upload zip completo, CLI genera una nuova AES-128 chiave di sessione e IV a 16 byte, cripta il bundle con AES-128-CBC, e cripta la session key con la tua RSA-2048 private key usando padding di tipo PKCS#1 v1.5 type 1 . I dispositivi recuperano la chiave AES tramite la RSA public key integrata nell'app. Chiavi e IV non vengono riutilizzati tra diversi upload di bundle CLI. All'interno di un singolo upload delta, tutti i file parziali criptati condividono la session key e l'IV di quell'upload.

La public key usata per la decriptazione è integrata nell'app rilasciata. Il contenuto in chiaro del bundle è accessibile sui dispositivi che eseguono l'app tramite lo stesso percorso di decriptazione dell'updater, in modo simile agli altri asset nel pacchetto dell'app.

Errori e reporting

Gli errori di decriptazione e di checksum vengono riportati come eventi statistici (download_fail, checksum_fail, decrypt_fail) all'endpoint stats di Capgo o al tuo gestore delle statistiche self-hosted. Le statistiche vengono inviate dal dispositivo; non viene riportato nulla agli host dei bundle di terze parti in base al successo o al fallimento della decrittazione. Ogni tentativo è solitamente un download completo avviato dal dispositivo, quindi i tentativi di probing in stile padding-oracle sono impraticabili e un testo in chiaro modificato fallirà comunque il controllo del checksum firmato.

Rafforzamento futuro

Un futuro rilascio major potrebbe aggiungere un formato versionato con AES-GCM e RSA-PSS sull'hash come difesa in profondità insieme al design attuale. Si tratterebbe di un passo incrementale di hardening, non di una correzione di sicurezza d'emergenza per il formato corrente.

Come funziona la crittografia

Capgo utilizza un approccio di crittografia ibrida che combina RSA e AES per garantire sicurezza e prestazioni ottimali:

1. Generazione delle chiavi

• Chiave privataGenerati e memorizzati in modo sicuro nel tuo ambiente di sviluppo (usati per la crittografia)
• Chiave pubblica: Derivata dalla chiave privata e salvata nella config Capacitor della tua app (usata per la decrittazione)
• Chiavi di sessione: Chiavi AES casuali generate per ogni bundle upload

2. Processo di crittografia

1. Viene generata una chiave di sessione AES casuale per ogni bundle upload
2. Il bundle è criptato con la chiave di sessione AES
3. Viene calcolato il checksum del bundle
4. Sia la chiave AES che il checksum vengono criptati insieme con la tua chiave RSA privata (creando la “signature”)
5. Il bundle e la signature criptati vengono salvati

Il checksum viene criptato insieme alla chiave AES per prevenire manomissioni. Poiché solo la tua chiave RSA privata può creare questa signature, e solo la relativa chiave pubblica può decriptarla, ciò garantisce che sia la chiave AES che il checksum siano autentici e non siano stati modificati da un attaccante.

3. Processo di decriptazione

1. L'app scarica il bundle e la signature criptati
2. Il Capgo SDK usa la tua chiave RSA pubblica (salvata nell'app) per decriptare la signature
3. Questo rivela la chiave di sessione AES e il checksum originale
4. La chiave di sessione AES viene usata per decriptare il bundle
5. Viene calcolato il checksum del bundle decriptato e confrontato con l'originale per la verifica dell'integrità

Questo processo garantisce che, anche se un attaccante intercettasse il bundle criptato, non potrebbe modificare la chiave di sessione AES o fornire un checksum falso, perché gli servirebbe la tua chiave privata per creare una firma valida che la chiave pubblica possa decriptare.

Tip

RSA non può crittografare grandi quantità di dati in modo efficiente, quindi AES viene usato per la crittografia effettiva del bundle, mentre RSA protegge la chiave AES e garantisce la verifica dell'integrità tramite la firma del checksum.

Capgo vs Altre Piattaforme

Funzionalità	Capgo	Altre piattaforme OTA
Contenuto del bundle	Crittografato in storage/transit; resta comunque ispezionabile da un reverse engineer determinato con il binario dell'app	Leggibile pubblicamente
Metodo di sicurezza	Vera crittografia end-to-end	Solo firma Code
Livello di privacy	Forte protezione di delivery/storage; non anti-reverse-engineering	La piattaforma può accedere ai tuoi code
Protezione	Contenuto + integrità + autenticità	Solo integrità + autenticità

Perché è importante:

• Firma Code verifica solo che gli update non siano stati manomessi e provengano dalla fonte corretta
• Crittografia Capgo protegge il bundle durante l'archiviazione e la distribuzione, rendendo molto più difficile la creazione di update contraffatti poiché l'attaccante necessiterebbe della tua chiave privata
• Il reverse engineering è ancora possibile dopo il rilascio dell'app, poiché il client contiene la chiave pubblica necessaria per decriptare e caricare l'update

Metodi di crittografia

Capgo utilizza Encryption V2 come metodo di crittografia standard:

Encryption V2 (Standard attuale)

• Utilizza RSA-4096 per una sicurezza avanzata
• AES-256-GCM per la crittografia autenticata
• Fornisce la verifica dell'integrità
• Performance e sicurezza migliori

Encryption V1 (Deprecata)

• Usa RSA-2048 per la cifratura delle chiavi
• AES-256-CBC per la cifratura del bundle
• Non più disponibile nell'attuale CLI
• Le app legacy che usano V1 devono migrare a V2

Pericolo

L'Encryption V1 non è più supportata nell'attuale Capgo CLI. Se utilizzi la cifratura V1, devi migrare a V2. Consulta la guida alla migrazione per istruzioni dettagliate.

Configurazione della crittografia

Passaggio 1: Genera le chiavi di crittografia

Per prima cosa, genera le tue chiavi di crittografia usando Capgo CLI:

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

Questo creerà:

• .capgo_key_v2: La tua chiave privata (tienila al sicuro!)
• .capgo_key_v2.pub: La tua chiave pubblica (usata dalla tua app)

I file vengono creati nella directory corrente in cui esegui il comando.

Attenzione

Note importanti sullo storage:

• Chiave Privata (.capgo_key_v2)Non committare mai questo file nel version control. Deve essere conservato in modo sicuro e utilizzato esclusivamente per la crittografia durante l'upload dei bundle.
• Chiave Pubblica (.capgo_key_v2.pub): Puoi caricarla tranquillamente su version control, essendo un backup della tua chiave pubblica.
• Posizione del file: Le chiavi vengono create nella directory corrente in cui esegui il key create comando.
• Chiave Pubblica in Config: Devi eseguire key save per salvare la chiave pubblica nella configurazione Capacitor dell'app mobile.

Per l'uso in produzione, conserva la chiave privata in modo sicuro (variabili d'ambiente, key management services) e rimuovila dal progetto locale dopo il setup.

Passaggio 2: Salva la chiave pubblica nella config di Capacitor (Obbligatorio)

Tu usare salva la tua chiave pubblica nella config di Capacitor per permettere alla tua app mobile di decriptare i bundle:

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

Dopo aver salvato la chiave pubblica, puoi usare sincronizza la piattaforma Capacitor per copiare la config aggiornata nel layer nativo:

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

Attenzione

Passaggi richiesti:

1. L'oggetto key save il comando salva la chiave pubblica nella tua config Capacitor
2. npx cap sync copia questa config nel layer nativo a cui l'app mobile può accedere
3. Senza entrambi i passaggi, l'app non potrà decriptare gli update criptati

Crittografia dei bundle

Metodo 1: crittografare durante l'upload

Il modo più semplice è crittografare durante il processo di 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)

Metodo 2: Workflow di crittografia manuale

Per avere più controllo, puoi crittografare i bundle manualmente:

1. Crea un bundle zip:

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

2. Crittografa il bundle:

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

3. Carica sul tuo storage (es. S3) e registra con 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

Gestione delle chiavi

Archiviazione sicura delle chiavi

Opzioni per la Private Key:

1. Basata su file (sviluppo locale):

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

2. Variabile d'ambiente (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"

Configurazione Chiave Pubblica (Richiesto):

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

Ambiente di Produzione:

• Memorizza le chiavi private in servizi di gestione sicura (AWS KMS, Azure Key Vault, ecc.)
• Usa la gestione dei secret CI/CD per le chiavi private
• Non committare mai le chiavi private nel version control

Key Usage:

• Chiave Privata: Utilizzato da CLI per la crittografia durante l'upload del bundle (mantieni al sicuro)
• Chiave Pubblica: Stored in app configuration for decryption on device (safe to commit)

Ruotare in caso di compromissione della chiave privata

Ruota la coppia di chiavi se si sospetta o si conferma la compromissione della chiave privata. Non è necessaria una rotazione periodica programmata. Si tratta di una migrazione della chiave nativa, non di una semplice modifica OTA.

1. Genera una nuova coppia di chiavi:

   npx @capgo/cli@latest key create

2. Salva la nuova chiave pubblica nella configurazione di Capacitor:

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

3. Sincronizza e rilascia una versione native: Esegui npx cap sync, quindi distribuisci una nuova versione native dell'app con la nuova chiave pubblica.

4. Punta alla nuova versione native: I dispositivi con la vecchia versione native non possono decriptare gli update con la nuova chiave. Usa Targeting delle versioni per limitare i bundle con la nuova chiave alla nuova versione native, mentre il resto del fleet si aggiorna tramite store o MDM.

5. Cambia il tuo upload secret: Non appena il rilascio native è live, sostituisci la chiave privata in CI e carica solo i bundle destinati alle versioni native che contengono la nuova chiave pubblica.

Attenzione

Se la chiave privata viene compromessa, smetti immediatamente di usarla. Le installazioni esistenti con la vecchia chiave pubblica richiedono un aggiornamento tramite native store o MDM prima di poter ricevere bundle criptati con la nuova chiave.

Best practice di sicurezza

Sicurezza delle chiavi

• Non condividere mai le chiavi private tra diversi ambienti o membri del team
• Usa chiavi diverse per i vari ambienti (dev, staging, production)
• Ruota dopo una compromissione: sostituisci la coppia di chiavi se si sospetta o si conferma la compromissione della chiave privata; non è necessaria una rotazione periodica programmata
• Archivia le chiavi in modo sicuro using proper key management systems

Sicurezza del bundle

• Verifica sempre l'integrità del bundle dopo la decrittazione
• Monitora per pattern di download insoliti o errori
• Usa HTTPS per tutti gli URL dei bundle (obbligatorio per le app mobile)
• Implementare una corretta gestione degli errori di decrittazione

Controllo degli accessi

• Limita l'accesso alle chiavi di cifratura solo al personale autorizzato
• Usa l'accesso basato sui ruoli per le operazioni di gestione delle chiavi
• Audit monitora regolarmente l'uso e l'accesso alle chiavi
• Implementare procedure corrette di backup e recovery

Troubleshooting della cifratura

Problemi comuni

Errori di decrittazione:

• Verifica che la chiave privata corrisponda alla chiave pubblica usata per la cifratura
• Controlla che il/la ivSessionKey sia corretto/a
• Assicurati di usare Encryption V2 (la V1 non è più supportata)

Errori relativi alle chiavi:

• Conferma che il formato della chiave privata sia corretto (formato PEM)
• Verifica che la chiave non sia stata corrotta durante l'archiviazione o il trasferimento
• Controlla che la chiave abbia i permessi corretti nella configurazione dell'app

Problemi di performance:

• Large bundles may take longer to encrypt/decrypt
• Considera l'uso di Delta update per ridurre la dimensione dei bundle
• Monitora le performance del dispositivo durante la decrittazione

Comandi di Debug

Controlla lo stato della crittografia:

npx @capgo/cli@latest app debug

Testa il workflow di crittografia/decrittazione:

# 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à e Standard

L'implementazione della crittografia di Capgo segue gli standard di settore:

• AES-256: Algoritmo di crittografia approvato FIPS 140-2
• RSA-4096: Crittografia asimmetrica forte per la protezione delle chiavi
• Modalità GCM: Garantisce sia la riservatezza che l'autenticità
• Generazione casuale sicura: Generazione di numeri casuali crittograficamente sicura

Questo rende Capgo adatto per applicazioni che richiedono la conformità a:

• GDPR (Regolamento generale sulla protezione dei dati)
• HIPAA (Health Insurance Portability and Accountability Act)
• SOC 2 (Service Organization Control 2)
• ISO 27001 (Gestione della sicurezza delle informazioni)

Considerazioni sulle performance

Overhead della crittografia

• Dimensione bundle: I bundle crittografati sono leggermente più grandi (~1-2% di overhead)
• Tempo di elaborazione: Crittografia/decrittografia con latenza minima
• Utilizzo della memoria: Incremento temporaneo durante le operazioni di crittografia/decrittografia

Consigli di ottimizzazione

• Usa gli aggiornamenti Delta per ridurre il trasferimento di dati criptati
• Ottimizza la dimensione del bundle convertendo le immagini in WebP
• Minimizza i file JavaScript e CSS prima del bundling
• Rimuovi le dipendenze inutilizzate e code
• Monitora le performance su dispositivi vecchi o lenti

Prossimi passi

• Scopri come Storage personalizzato usare la crittografia con la tua infrastruttura
• Esplora Canali per gestire i bundle criptati tra gli ambienti
• Configurazione Integrazione CI/CD per automatizzare i deployment criptati

Continua da Encryption

Se stai usando Crittografia per pianificare sicurezza e compliance, collegalo a Conformità per i dettagli di implementazione in Compliance, Security Scanner di Capgo per il workflow del prodotto in Capgo Security Scanner, Sicurezza Capgo per il workflow di Capgo Security, Trust Center di Capgo per il workflow di Capgo Trust Center, e Sicurezza dell'organizzazione per i dettagli di implementazione in Organization Security.