Vai al contenuto

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 è pensato per darti il controllo completo sulla sicurezza della tua app, mantenendo la comodità degli aggiornamenti live.

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 rimangono tali finché l'app non li decifra sul dispositivo dell'utente.

Cosa protegge realmente 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 accidentali durante lo storage o il transito e garantisce che solo chi possiede la tua chiave privata possa generare un aggiornamento criptato valido. Questo hai non rende impossibile il reverse engineering degli asset web distribuiti: la chiave pubblica usata dal client per decifrare gli aggiornamenti è inclusa nell'app, quindi un attaccante determinato può comunque estrarla e ispezionare il contenuto del bundle con sufficiente impegno.

Modello di sicurezza

La tua chiave privata RSA viene generata e conservata sulla tua macchina. Capgo CLI non trasmette mai la tua chiave privata e Capgo non la memorizza. Neppure Capgo 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.

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 è hai uguale al tuo iOS bundle ID o Android application ID. 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. Capgo Builder carica il tuo progetto zip 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 build di app native localmente o nella tua CI quando la riservatezza verso 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 ogni Builder che non deve esporre la chiave ha completato l'upload, o
  • Se usi Capgo Builder per i build nativi, considera il workflow come un sistema che offre una forte integrità (checksum firmati) ma non hai garantisce la riservatezza di Capgo una volta inclusa la chiave pubblica in un upload del Builder.

Crittografa gli upload delta. I contenuti 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 sulle versioni supportate dell'updater) o passa --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.

Dopo la decrittazione, l'updater calcola lo 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 scompattando l'archivio.
  • iOS prima decripta e scompatta, 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.

Per ogni upload zip completo, CLI genera una nuova AES-128 chiave di sessione casuale 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 è disponibile sui dispositivi che eseguono l'app tramite lo stesso percorso di decriptazione dell'updater, in modo simile agli altri asset nel pacchetto dell'app.

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 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 plaintext modificato fallirà comunque il checksum firmato.

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.

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

Flusso di crittografia Capgo

  • Chiave privataGenerati e memorizzati in modo sicuro nel tuo ambiente di sviluppo (usati per la crittografia)
  • Chiave pubblica: Derivata dalla tua 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
  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. La chiave di sessione AES e il checksum vengono criptati insieme usando la tua chiave privata RSA (creando la “signature”)
  5. Il bundle criptato e la signature criptata vengono salvati

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

  1. L'app scarica il bundle e la signature criptati
  2. Il Capgo SDK usa la tua chiave pubblica RSA (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 quello originale per la verifica dell'integrità

Questo processo garantisce che, anche se un attaccante intercetta il bundle criptato, non possa modificarne la session key AES né fornire un checksum falso, perché gli servirebbe la tua chiave privata per creare una firma valida che la chiave pubblica possa decifrare.

FunzionalitàCapgoAltre piattaforme OTA
Contenuto del bundleCriptato durante archiviazione e transito; comunque ispezionabile da un reverse engineer determinato con il binario dell'appLeggibile pubblicamente
Metodo di sicurezzaVera crittografia end-to-endSolo firma Code
Livello di privacyForte protezione in transito/storage; non anti-reverse-engineeringLa piattaforma può accedere ai tuoi code
ProtezioneContenuto + integrità + autenticitàSolo integrità + autenticità

Perché è importante:

  • Firma di 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

Capgo utilizza Encryption V2 come metodo di crittografia standard:

  • Utilizza RSA-4096 per una sicurezza avanzata
  • AES-256-GCM per la crittografia autenticata
  • Fornisce la verifica dell'integrità
  • Più performance e sicurezza
  • 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

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

Finestra del terminale
# 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.

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

Sezione intitolata “Passaggio 2: Salva la chiave pubblica nella config di Capacitor (Obbligatorio)”

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

Finestra del terminale
# 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"

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

Finestra del terminale
# Sync the platform to copy config to native
npx cap sync

Il modo più semplice è crittografare durante il processo di upload:

Finestra del terminale
# Upload with automatic encryption
npx @capgo/cli@latest bundle upload --key-v2
# For external storage, you must encrypt first (see Manual Encryption Workflow below)

Per un controllo maggiore, puoi crittografare i bundle manualmente:

  1. Crea un bundle zip:

    Finestra del terminale
    npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2
  2. Crittografa il bundle:

    Finestra del terminale
    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:

    Finestra del terminale
    # 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

Archiviazione sicura delle chiavi

Sezione intitolata “Storing Keys Securely”

Opzioni per la Private Key:

  1. Basata su file (sviluppo locale):

    Finestra del terminale
    # Key stored as .capgo_key_v2 file in project root
    npx @capgo/cli@latest bundle upload --key-v2
  2. Variabile d'ambiente (CI/CD):

    Finestra del terminale
    # 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 (Obbligatoria):

Finestra del terminale
# 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 (da mantenere sicuro)
  • Chiave pubblica: Stored in app configuration for decryption on device (safe to commit)

Ruotare in caso di compromissione della chiave privata

Sezione: “Rotazione 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 delle chiavi native, non di una semplice modifica OTA.

  1. Genera una nuova coppia di chiavi:

    Finestra del terminale
    npx @capgo/cli@latest key create
  2. Salva la nuova chiave pubblica nella configurazione di Capacitor:

    Finestra del terminale
    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 dell'app native 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 nella CI e carica solo i bundle destinati alle versioni native che contengono la nuova chiave pubblica.

Sicurezza delle chiavi

Sezione: "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
  • 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
  • Limita l'accesso alle chiavi di cifratura solo al personale autorizzato
  • Utilizza l'accesso basato sui ruoli per le operazioni di gestione delle chiavi
  • Verifica regolarmente l'uso e l'accesso alle chiavi
  • Implementare procedure adeguate di backup e recovery

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
  • Valuta l'uso di Delta updates per ridurre la dimensione dei bundle
  • Monitora le performance del dispositivo durante la decrittazione

Controlla lo stato della crittografia:

Finestra del terminale
npx @capgo/cli@latest app debug

Testa il workflow di crittografia/decrittazione:

Finestra del terminale
# 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

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 ideale 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

Sezione "Considerazioni sulle performance"

Overhead della crittografia

Sezione "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 memoria: Incremento temporaneo durante le operazioni di crittografia/decrittografia
  • 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

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 prodotto in Capgo Security, Trust Center di Capgo per il workflow di prodotto in Capgo Trust Center, e Sicurezza dell'organizzazione per i dettagli di implementazione in Organization Security.