Transparence du code pour les app bundles

La transparence du code est un mécanisme facultatif de signature et de validation de code pour les applications publiées avec Android App Bundle. Il utilise une clé de signature de transparence du code, détenue uniquement par le développeur de l'application.

La transparence du code est indépendante du schéma de signature utilisé pour les app bundles et les APK. La clé de transparence du code est distincte de la clé de signature d'application stockée sur l'infrastructure sécurisée de Google lorsque vous utilisez la signature d'application Play.

Fonctionnement de la transparence du code

Le processus consiste à inclure un fichier de transparence de code dans le bundle après sa création, mais avant de l'importer dans la Play Console pour la distribution.

Le fichier de transparence du code est un jeton Web JSON (JWT, JSON Web Token) contenant une liste de fichiers DEX et de bibliothèques natives inclus dans le bundle, ainsi que leurs hachages. Il est ensuite signé à l'aide de la clé de transparence du code qui n'est détenue que par le développeur.

Schéma de transparence du code

Ce fichier de transparence du code est propagé vers l'APK de base créé à partir de l'app bundle (en particulier dans la division principale du module de base). Vous pouvez ensuite vérifier que :

  • Tous les fichiers DEX et de code natif présents dans les APK présentent des hachages correspondants dans le fichier de transparence du code.
  • Le composant de clé publique de la clé de signature de transparence du code dans l'application correspond à la clé publique du développeur (qui doit être fournie par le développeur via un canal distinct et sécurisé).

Ensemble, ces informations permettent de vérifier que le code contenu dans les APK correspond à celui du développeur et qu'il n'a pas été modifié.

Le fichier de transparence du code ne vérifie pas les ressources, les éléments, le fichier manifeste Android ni aucun autre fichier autre que les fichiers DEX ou les bibliothèques natives contenus dans le dossier lib/.

La validation de la transparence du code n'est utilisée que pour inspection par les développeurs et les utilisateurs finaux, qui souhaitent s'assurer que le code qu'ils exécutent correspond au code initialement créé et signé par le développeur de l'application.

Limites connues

Dans certains cas, la transparence du code ne peut pas être utilisée :

  • Applications qui spécifient l'attribut sharedUserId dans le fichier manifeste. Ces applications peuvent partager leur processus avec d'autres applications, ce qui rend difficile toute vérification du code qu'elles exécutent.
  • Les applications qui utilisent une protection contre la falsification ou tout autre service qui modifie le code après la génération du fichier de transparence du code font échouer la vérification de la transparence du code.
  • Applications qui utilisent l'ancien multidex pour les niveaux d'API inférieurs à 21 (Android 5.0) et qui utilisent des modules de fonctionnalités. La transparence du code continue de fonctionner lorsque l'application est installée par Google Play sur des appareils Android 5.0 ou version ultérieure. La transparence du code sera désactivée sur les anciennes versions de l'OS.

Utiliser la transparence du code

Avant d'ajouter la transparence du code à votre application, assurez-vous de disposer d'une paire de clés publique et privée que vous pouvez utiliser pour la signature de la transparence du code. Il doit s'agir d'une clé unique différente de la clé de signature d'application que vous utilisez pour la signature d'application Play. Elle doit être détenue de manière sécurisée et ne doit jamais être partagée en dehors de votre organisation.

Si vous n'avez pas de clé, vous pouvez suivre les instructions du guide Signer votre application pour en générer une sur votre machine. La transparence du code utilise un fichier keystore standard. Par conséquent, même si le guide est destiné à la signature d'application, le processus de génération de clés est le même.

Utiliser le plug-in Android Gradle

La prise en charge de la transparence du code nécessite le plug-in Android Gradle 7.1.0-alpha03 ou version ultérieure. Pour configurer la clé utilisée pour la signature de la transparence du code, ajoutez le code suivant dans le bloc bundle.

Groovy

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

Kotlin

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

Il doit s'agir d'une clé que vous n'utiliserez que pour la transparence du code, et non de la clé de signature d'application utilisée par la signature d'application Play.

Utiliser bundletool sur la ligne de commande

La prise en charge de la transparence du code nécessite la version 1.7.0 ou ultérieure de bundletool, que vous pouvez télécharger à partir de GitHub.

Exécutez la commande suivante pour ajouter la transparence du code à un Android App Bundle. Il doit s'agir d'une clé que vous n'utiliserez que pour la transparence du code, et non de la clé de signature d'application utilisée par la signature d'application 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

Si vous souhaitez utiliser vos propres outils de signature, vous pouvez utiliser bundletool pour générer le fichier de transparence du code non signé, le signer dans un environnement distinct et injecter la signature dans le 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

Vérifier la transparence du code d'une application

Il existe différentes méthodes de vérification du code par rapport au fichier de transparence du code, selon que vous avez installé les APK sur un appareil Android ou que vous les avez téléchargés localement sur votre ordinateur.

Utiliser Bundletool pour vérifier un app bundle ou un ensemble d'APK

Vous pouvez utiliser bundletool pour vérifier la transparence du code dans un app bundle ou un ensemble d'APK. Utilisez la commande check-transparency pour afficher l'empreinte du certificat public :

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

Vous pouvez éventuellement spécifier le certificat public avec lequel vous souhaitez valider le bundle ou l'ensemble d'APK, afin de ne pas avoir à comparer manuellement les hachages :

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.

Utiliser Bundletool pour vérifier une application installée sur un appareil

Pour vérifier une application installée sur un appareil Android, assurez-vous que l'appareil est connecté à votre ordinateur via ADB et exécutez la commande suivante :

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.

Le contrôle de transparence de l'appareil connecté peut également vérifier la signature par rapport à une clé publique que vous spécifiez :

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.