Trasparenza del codice per app bundle

La trasparenza del codice è un meccanismo facoltativo di firma e verifica del codice per le app pubblicate con Android App Bundle. Usa una chiave di firma della trasparenza del codice che è detenuta esclusivamente dallo sviluppatore dell'app.

La trasparenza del codice è indipendente dallo schema di firma utilizzato per gli app bundle e gli APK. La chiave di trasparenza del codice è separata e diversa dalla chiave di firma dell'app archiviata nell'infrastruttura sicura di Google durante l'utilizzo della firma dell'app di Google Play.

Come funziona la trasparenza del codice

Il processo funziona includendo un file di trasparenza del codice nel bundle dopo la creazione, ma prima che venga caricato su Play Console per la distribuzione.

Il file di trasparenza del codice è un token JWT (JSON Web Token) che contiene un elenco di file DEX e librerie native incluse nel bundle, con i relativi hash. Viene quindi firmato utilizzando la chiave di trasparenza del codice che è in possesso solo dello sviluppatore.

Questo file di trasparenza del codice viene propagato all'APK di base creato dall'app bundle (in particolare alla suddivisione principale del modulo di base). È quindi possibile verificare che:

• Tutti i file DEX e di codice nativo presenti negli APK hanno hash corrispondenti nel file di trasparenza del codice.
• Il componente della chiave pubblica della chiave di firma della trasparenza del codice nell'app corrisponde alla chiave pubblica dello sviluppatore (che deve essere fornita dallo sviluppatore tramite un canale sicuro separato).

Insieme, queste informazioni consentono di verificare che il codice contenuto negli APK corrisponda a quello previsto dallo sviluppatore e che non sia stato modificato.

Il file di trasparenza del codice non verifica le risorse, gli asset, il manifest Android o qualsiasi altro file che non sia file DEX o librerie native contenuti nella cartella lib/.

La verifica della trasparenza del codice viene utilizzata esclusivamente ai fini dell'ispezione da parte di sviluppatori e utenti finali, che vogliono garantire che il codice in esecuzione corrisponda al codice originariamente creato e firmato dallo sviluppatore di app.

Limitazioni note

Non è possibile utilizzare la trasparenza del codice in alcune situazioni:

• App che specificano l'attributo sharedUserId nel file manifest. Queste applicazioni potrebbero condividere il loro processo con altre applicazioni, il che rende difficile fornire garanzie sul codice che stanno eseguendo.
• Le app che utilizzano la protezione dalle manomissioni o qualsiasi altro servizio che apporta modifiche al codice dopo la generazione del file di trasparenza del codice causeranno un errore nella verifica della trasparenza del codice.
• App che utilizzano la versione precedente di Multidex su livelli API inferiori a 21 (Android 5.0) e che utilizzano moduli di funzionalità. La trasparenza del codice continuerà a funzionare quando l'app verrà installata da Google Play sui dispositivi Android 5.0 e versioni successive. La trasparenza del codice verrà disabilitata nelle versioni precedenti del sistema operativo.

Come aggiungere trasparenza del codice

Prima di poter aggiungere trasparenza del codice alla tua app, assicurati di disporre di una coppia di chiavi privata e pubblica da utilizzare per la firma della trasparenza del codice. Deve essere una chiave univoca diversa dalla chiave di firma dell'app che utilizzi per la firma dell'app di Google Play e deve essere conservata in modo sicuro e non deve mai essere condivisa all'esterno della tua organizzazione.

Se non disponi di una chiave, puoi seguire le istruzioni nella guida Firma l'app per generarne una sulla tua macchina. La trasparenza del codice utilizza un file di archivio chiavi standard. Pertanto, anche se la guida si riferisce alla firma dell'app, il processo di generazione delle chiavi è lo stesso.

Utilizzo del plug-in Android per Gradle

Il supporto per la trasparenza del codice richiede il plug-in Android per Gradle versione 7.1.0-alpha03 o successive. Per configurare la chiave utilizzata per la firma della trasparenza del codice, aggiungi quanto segue nel blocco bundle.

// In your app module's build.gradle file:
android {
    ...
    bundle {
        codeTransparency {
            signing {
                keyAlias = "ALIAS"
                keyPassword = "PASSWORD"
                storeFile = file("path/to/keystore")
                storePassword = "PASSWORD"
            }
        }
        ...
    }
}

// In your app module's build.gradle.kts file:
android {
    ...
    bundle {
        codeTransparency {
            signing {
                keyAlias = "ALIAS"
                keyPassword = "PASSWORD"
                storeFile = file("path/to/keystore")
                storePassword = "PASSWORD"
            }
        }
        ...
    }
}

La chiave utilizzata deve essere quella che userai soltanto per la trasparenza del codice e non la chiave di firma dell'app utilizzata dalla funzionalità di firma dell'app di Google Play.

Utilizzo di bundletool nella riga di comando

Il supporto per la trasparenza del codice richiede bundletool versione 1.7.0 o successiva, che puoi scaricare da GitHub.

Esegui questo comando per aggiungere trasparenza del codice a un Android App Bundle. La chiave utilizzata deve essere quella che userai soltanto per la trasparenza del codice e non la chiave di firma dell'app utilizzata dalla funzionalità di firma dell'app di Google Play.

bundletool add-transparency \
  --bundle=/MyApp/my_app.aab \
  --output=/MyApp/my_app_with_transparency.aab \
  --ks=/MyApp/keystore.jks \
  --ks-pass=file:/MyApp/keystore.pwd \
  --ks-key-alias=MyKeyAlias \
  --key-pass=file:/MyApp/key.pwd

In alternativa, se vuoi usare strumenti di firma personalizzati, puoi usare bundletool per generare il file di trasparenza del codice senza firma, firmarlo in un ambiente separato e inserire la firma nel bundle:

# Generate code transparency file
bundletool add-transparency \
  --mode=generate_code_transparency_file \
  --bundle=/MyApp/my_app.aab \
  --output=/MyApp/code_transparency_file.jwt \
  --transparency-key-certificate=/MyApp/transparency.cert

# Add code transparency signature to the bundle
bundletool add-transparency \
  --mode=inject_signature \
  --bundle=/MyApp/my_app.aab \
  --output=/MyApp/my_app_with_transparency.aab \
  --transparency-key-certificate=/MyApp/transparency.cert \
  --transparency-signature=/MyApp/signature

Verificare la trasparenza del codice di un'app

Esistono diversi metodi per verificare il codice rispetto al file di trasparenza del codice, a seconda che gli APK siano installati su un dispositivo Android o scaricati localmente sul computer.

Utilizzare Bundletool per controllare un app bundle o un set di APK

Puoi usare bundletool per verificare la trasparenza del codice in un app bundle o in un set di APK. Utilizza il comando check-transparency per stampare la fingerprint del certificato pubblico:

# For checking a bundle:
bundletool check-transparency \
  --mode=bundle \
  --bundle=/MyApp/my_app_with_transparency.aab

No APK present. APK signature was not checked.
Code transparency signature is valid. SHA-256 fingerprint of the code transparency key certificate (must be compared with the developer's public key manually): 01 23 45 67 89 AB CD EF ..
Code transparency verified: code related file contents match the code transparency file.


# For checking a ZIP containing app's APK splits:
bundletool check-transparency \
  --mode=apk \
  --apk-zip=/MyApp/my_app_with_transparency.zip

APK signature is valid. SHA-256 fingerprint of the apk signing key certificate (must be compared with the developer's public key manually): 02 34 E5 98 CD A7 B2 12 ..
Code transparency signature is valid. SHA-256 fingerprint of the code transparency key certificate (must be compared with the developer's public key manually): 01 23 45 67 89 AB CD EF ..
Code transparency verified: code related file contents match the code transparency file.

Facoltativamente, puoi specificare il certificato pubblico in base al quale vuoi verificare il bundle o l'APK, in modo da non dover confrontare manualmente gli hash:

bundletool check-transparency \
  --mode=bundle \
  --bundle=/MyApp/my_app_with_transparency.aab \
  --transparency-key-certificate=/MyApp/transparency.cert

No APK present. APK signature was not checked.
Code transparency signature verified for the provided code transparency key certificate.
Code transparency verified: code related file contents match the code transparency file.


bundletool check-transparency \
  --mode=apk \
  --apk-zip=/MyApp/my_app_with_transparency.zip \
  --apk-signing-key-certificate=/MyApp/apk.cert \
  --transparency-key-certificate=/MyApp/transparency.cert

APK signature verified for the provided apk signing key certificate.
Code transparency signature verified for the provided code transparency key certificate.
Code transparency verified: code related file contents match the code transparency file.

Utilizzare Bundletool per controllare un'app installata su un dispositivo

Per controllare un'app che è stata installata su un dispositivo Android, assicurati che il dispositivo sia connesso al tuo computer tramite ADB e invia il seguente comando:

bundletool check-transparency \
  --mode=connected_device \
  --package-name="com.my.app"

APK signature is valid. SHA-256 fingerprint of the apk signing key certificate (must be compared with the developer's public key manually): 02 34 E5 98 CD A7 B2 12 ..
Code transparency signature is valid. SHA-256 fingerprint of the code transparency key certificate (must be compared with the developer's public key manually): 01 23 45 67 89 AB CD EF ..
Code transparency verified: code related file contents match the code transparency file.

Il controllo di trasparenza del dispositivo connesso può anche facoltativamente verificare la firma utilizzando una chiave pubblica da te specificata:

bundletool check-transparency \
  --mode=connected-device \
  --package-name="com.my.app" \
  --apk-signing-key-certificate=/MyApp/apk.cert \
  --transparency-key-certificate=/MyApp/transparency.cert

APK signature verified for the provided apk signing key certificate.
Code transparency signature verified for the provided code transparency key certificate.
Code transparency verified: code related file contents match the code transparency file.