Codetransparenz für App Bundles

Codetransparenz ist ein optionaler Mechanismus zur Codesignierung und -überprüfung für Apps, die mit dem Android App Bundle veröffentlicht werden. Sie verwendet einen Signaturschlüssel für Codetransparenz, der ausschließlich dem App-Entwickler gehört.

Codetransparenz ist unabhängig vom Signaturschema, das für App Bundles und APKs verwendet wird. Wenn Sie Play App-Signatur verwenden, unterscheidet sich der Codetransparenzschlüssel vom App-Signaturschlüssel, der in der sicheren Infrastruktur von Google gespeichert wird.

So funktioniert Codetransparenz

Dazu wird eine Codetransparenzdatei in das Bundle eingebunden, nachdem es erstellt wurde, aber vor dem Hochladen in die Play Console zum Vertrieb.

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. Er wird dann mit dem Codetransparenzschlüssel signiert, der nur dem Entwickler zugewiesen ist.

Codetransparenzdiagramm

Diese Codetransparenzdatei wird an das Basis-APK weitergegeben, das aus dem App Bundle erstellt wurde (insbesondere an den Hauptteil des Basismoduls). Dann kann überprüft werden, ob:

  • Alle in den APKs vorhandenen DEX- und nativen Codedateien haben übereinstimmende Hashes in der Codetransparenzdatei.
  • Die Public-Key-Komponente des Codetransparenz-Signaturschlüssels 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 native Bibliotheken im Ordner lib/ sind.

Die Verifizierung der Codetransparenz wird ausschließlich zur Prüfung durch Entwickler und Endnutzer verwendet, die sicherstellen möchten, dass der ausgeführte Code mit dem Code übereinstimmt, der ursprünglich vom App-Entwickler erstellt und signiert wurde.

Bekannte Einschränkungen

In bestimmten Situationen kann Codetransparenz nicht verwendet werden:

  • Apps, die im Manifest das Attribut sharedUserId angeben Solche Anwendungen teilen ihren Prozess möglicherweise mit anderen Anwendungen, was es erschwert, Zusicherungen über den von ihnen ausgeführten Code zu geben.
  • Anwendungen, die den Manipulationsschutz verwenden, oder andere Dienste, die Codeänderungen nach dem Generieren der Codetransparenzdatei vornehmen, führen dazu, dass die Verifizierung der Codetransparenz fehlschlägt.
  • Apps, die Legacy-Multidex auf API-Levels unter 21 (Android 5.0) verwenden und Funktionsmodule nutzen. Codetransparenz funktioniert auch, wenn die App über Google Play auf Geräten mit Android 5.0 oder höher installiert wird. Codetransparenz wird bei älteren Betriebssystemversionen deaktiviert.

Codetransparenz hinzufügen

Bevor Sie Ihrer Anwendung Codetransparenz hinzufügen können, benötigen Sie ein Paar aus privatem und öffentlichem Schlüssel, das Sie für das Signieren mit Codetransparenz verwenden können. Dies sollte ein eindeutiger Schlüssel sein, der sich von dem App-Signaturschlüssel unterscheidet, den Sie für die Play App-Signatur verwenden. Er muss sicher aufbewahrt und niemals außerhalb Ihrer Organisation weitergegeben werden.

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

Android-Gradle-Plug-in verwenden

Um Codetransparenz zu unterstützen, ist das Android Gradle-Plug-in Version 7.1.0-alpha03 oder höher erforderlich. Zum Konfigurieren des Schlüssels, der für die Codetransparenzsignatur verwendet wird, fügen Sie Folgendes in den bundle-Block ein.

Groovig

// 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 muss nur für Codetransparenz verwendet werden, nicht der App-Signaturschlüssel, der von der Play App-Signatur verwendet wird.

bundletool in der Befehlszeile verwenden

Zur Unterstützung der Codetransparenz ist Bundletool Version 1.7.0 oder höher erforderlich, das 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 muss nur für Codetransparenz verwendet werden, nicht der App-Signaturschlüssel, der von der 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 prüfen

Es gibt verschiedene Methoden, um den Code anhand der Codetransparenzdatei zu verifizieren, je nachdem, ob Sie die APKs auf einem Android-Gerät installiert oder lokal auf Ihren Computer heruntergeladen haben.

Mit Bundletool ein App Bundle oder APK-Set prüfen

Mit „bundletool“ lässt sich die Codetransparenz in einem App Bundle oder einem APK-Set prüfen. Verwenden Sie den Befehl check-transparency, um den Fingerabdruck des öffentlichen Zertifikats auszudrucken:

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

Sie können optional das öffentliche Zertifikat angeben, mit dem das Set oder APK verglichen 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 Android-Gerät installiert wurde, achten Sie darauf, dass das Gerät über ADB mit Ihrem Computer verbunden ist, und geben Sie 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.

Die Transparenzprüfung für verbundene Geräte kann optional auch die Signatur anhand eines öffentlichen Schlüssels verifizieren, den Sie angeben:

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.