Codetransparenz für App Bundles

Die Codetransparenz ist ein optionaler Mechanismus zum Signieren und Verifizieren von Code für Apps, die mit dem Android App Bundle veröffentlicht werden. Dabei wird ein Signaturschlüssel für die Codetransparenz verwendet, der ausschließlich im Besitz des App-Entwicklers ist.

Die Codetransparenz ist unabhängig vom Signaturschema, das für App-Bundles und APKs verwendet wird. Der Codetransparenzschlüssel ist ein anderer Schlüssel als der App-Signaturschlüssel, der bei Verwendung der Play App-Signatur in der sicheren Infrastruktur von Google gespeichert wird.

Funktionsweise der Codetransparenz

Dazu wird nach dem Erstellen des Bundles, aber vor dem Hochladen in die Play Console zur Veröffentlichung, eine Codetransparenzdatei in das Bundle eingefügt.

Die Codetransparenzdatei ist ein JSON Web Token (JWT), das eine Liste der im Bundle enthaltenen DEX-Dateien und nativen Bibliotheken sowie deren Hashes enthält. Anschließend wird sie mit dem Codetransparenzschlüssel signiert, der nur dem Entwickler vorliegt.

Diagramm zur Codetransparenz

Diese Codetransparenzdatei wird an das Basis-APK weitergegeben, das aus dem App-Bundle erstellt wurde (insbesondere an den Hauptsplit des Basismoduls). Anschließend kann Folgendes überprüft werden:

  • Alle in den APKs vorhandenen DEX- und nativen Codedateien haben übereinstimmende Hashes in der Codetransparenzdatei.
  • Die Komponente des öffentlichen Schlüssels des Signaturschlüssels für die Codetransparenz in der App stimmt mit dem öffentlichen Schlüssel des Entwicklers überein, der vom Entwickler über einen separaten, sicheren Kanal bereitgestellt werden muss.

Zusammen bestätigen diese Informationen, dass der in den APKs enthaltene Code dem entspricht, was der Entwickler beabsichtigt hat, und dass er nicht geändert wurde.

Die Codetransparenzdatei überprüft keine Ressourcen, Assets, das Android-Manifest oder andere Dateien, die keine DEX-Dateien oder nativen Bibliotheken im Ordner lib/ sind.

Die Codetransparenzprüfung dient ausschließlich der Überprüfung durch Entwickler und Endnutzer, die sicherstellen möchten, dass der von ihnen ausgeführte Code mit dem Code übereinstimmt, der ursprünglich vom App-Entwickler erstellt und signiert wurde.

Bekannte Einschränkungen

In bestimmten Situationen kann die Codetransparenz nicht verwendet werden:

  • Apps, die das Attribut sharedUserId im Manifest angeben. Solche Anwendungen können ihren Prozess mit anderen Anwendungen teilen, was es schwierig macht, Zusicherungen über den von ihnen ausgeführten Code zu machen.
  • Bei Apps, die einen Manipulationsschutz oder einen anderen Dienst verwenden, der nach dem Erstellen der Codetransparenzdatei Codeänderungen vornimmt, schlägt die Codetransparenzprüfung fehl.
  • Apps, die das alte Multidex auf API-Levels unter 21 (Android 5.0) und Funktionsmodule verwenden. Die Codetransparenz funktioniert weiterhin, wenn die App von Google Play auf Geräten mit Android 5.0 oder höher installiert wird. Die Codetransparenz wird auf älteren Betriebssystemversionen deaktiviert.

Codetransparenz hinzufügen

Bevor Sie Ihrer App Codetransparenz hinzufügen können, benötigen Sie ein privates und öffentliches Schlüsselpaar, das Sie für die Codetransparenzsignatur verwenden können. Dieser Schlüssel muss eindeutig sein und sich von dem App-Signaturschlüssel unterscheiden, den du für die Play App-Signatur verwendest. Er muss sicher aufbewahrt und darf nicht außerhalb deiner Organisation weitergegeben werden.

Wenn Sie keinen Schlüssel haben, können Sie der Anleitung unter App signieren folgen, um einen auf Ihrem Computer zu generieren. Für die Codetransparenz wird eine Standard-Schlüsselspeicherdatei verwendet. Obwohl sich der Leitfaden auf die App-Signatur bezieht, ist der Prozess zur Schlüsselgenerierung derselbe.

Android-Gradle-Plug-in verwenden

Für die Unterstützung der Codetransparenz ist das Android-Gradle-Plug-in in Version 7.1.0-alpha03 oder höher erforderlich. Fügen Sie im Block bundle Folgendes hinzu, um den Schlüssel zu konfigurieren, der für die Codetransparenzsignierung verwendet wird.

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"
            }
        }
        ...
    }
}

Der verwendete Schlüssel darf nur für die Codetransparenz verwendet werden und nicht der App-Signaturschlüssel sein, der für die Play App-Signatur verwendet wird.

bundletool in der Befehlszeile verwenden

Für die Codetransparenz ist die bundletool-Version 1.7.0 oder höher erforderlich, die Sie von GitHub herunterladen können.

Führen Sie den folgenden Befehl aus, um einem Android App Bundle Codetransparenz hinzuzufügen. Der verwendete Schlüssel darf nur für die Codetransparenz verwendet werden und nicht der App-Signaturschlüssel sein, der für die Play App-Signatur verwendet wird.

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

Wenn Sie Ihre eigenen Signaturtools verwenden möchten, können Sie mit bundletool die unsignierte Codetransparenzdatei generieren, sie in einer separaten Umgebung signieren und die Signatur in das Bundle einfügen:

# 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

Codetransparenz einer App überprüfen

Es gibt verschiedene Methoden, um Code mit der Codetransparenzdatei abzugleichen. Welche Methode Sie verwenden, hängt davon ab, ob die APKs auf einem Android-Gerät installiert oder lokal auf Ihren Computer heruntergeladen wurden.

App-Bundle oder APK-Set mit Bundletool prüfen

Mit bundletool können Sie die Codetransparenz in einem App-Bundle oder APK-Satz prüfen. Verwenden Sie den Befehl check-transparency, um den Fingerabdruck des öffentlichen Zertifikats auszugeben:

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

Optional können Sie das öffentliche Zertifikat angeben, mit dem das Bundle oder APK-Set überprüft werden soll, damit Sie die Hashes nicht manuell vergleichen müssen:

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.

Mit Bundletool eine auf einem Gerät installierte App prüfen

Wenn Sie eine App prüfen möchten, die auf einem Gerät mit Android installiert ist, muss das Gerät über ADB mit Ihrem Computer verbunden sein. Führen Sie dann den folgenden Befehl aus:

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.

Bei der Transparenzprüfung für verbundene Geräte kann die Signatur optional auch mit einem von Ihnen angegebenen öffentlichen Schlüssel verifiziert werden:

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.