apksigner

Mit dem Tool apksigner, das in den Android SDK Build Tools ab Version 24.0.3 verfügbar ist, können Sie APKs signieren und sicherstellen, dass die Signatur des APKs auf allen Versionen der Android-Plattform verifiziert wird, die dieses APK unterstützt.

Auf dieser Seite finden Sie eine kurze Anleitung zur Verwendung des Tools sowie eine Referenz für die verschiedenen Befehlszeilenoptionen, die das Tool unterstützt. Eine ausführlichere Beschreibung der Verwendung des apksigner-Tools zum Signieren von APKs finden Sie unter App signieren.

Achtung : Wenn Sie Ihr APK mit apksigner signieren und weitere Änderungen am APK vornehmen, wird die Signatur des APK ungültig. Wenn Sie zipalign verwenden, um Ihr APK auszurichten, tun Sie dies, bevor Sie das APK signieren.

Nutzung

APK signieren

Die Syntax zum Signieren eines APK mit dem apksigner-Tool lautet so:

apksigner sign --ks keystore.jks |
  --key key.pk8 --cert cert.x509.pem
  [signer_options] app-name.apk

Wenn Sie ein APK mit dem Tool apksigner signieren, müssen Sie den privaten Schlüssel und das Zertifikat des Unterzeichners angeben. Sie haben zwei Möglichkeiten, diese Informationen anzugeben:

• Geben Sie mit der Option --ks eine KeyStore-Datei an.
• Geben Sie die Datei mit dem privaten Schlüssel und die Zertifikatsdatei separat mit den Optionen --key bzw. --cert an. Die Datei mit dem privaten Schlüssel muss das PKCS #8-Format und die Zertifikatsdatei das X.509-Format verwenden.

Normalerweise signieren Sie ein APK nur mit einem Signierer. Wenn Sie ein APK mit mehreren Unterzeichnern signieren müssen, verwenden Sie die Option --next-signer, um die Gruppe der allgemeinen Optionen zu trennen, die für jeden Unterzeichner gelten sollen:

apksigner sign [signer_1_options] --next-signer [signer_2_options] app-name.apk

Signatur eines APK prüfen

Die entsprechende Syntax lautet:

apksigner verify [options] app-name.apk

Signaturschlüssel rotieren

Die Syntax für die Rotation einer Signaturzertifikatskette oder einer neuen Signaturfolge lautet so:

$ apksigner rotate --in /path/to/existing/lineage \
  --out /path/to/new/file \
  --old-signer --ks old-signer-jks \
  --new-signer --ks new-signer-jks

Optionen

In den folgenden Listen sind die Optionen für jeden Befehl aufgeführt, die vom apksigner-Tool unterstützt werden.

Sign-Befehl

Der Befehl apksigner sign hat die folgenden Optionen.

Allgemeine Optionen

Mit den folgenden Optionen werden grundlegende Einstellungen für einen Unterzeichner angegeben:

--out <apk-filename>

Der Speicherort, an dem Sie das signierte APK speichern möchten. Wenn diese Option nicht explizit angegeben wird, wird das APK-Paket direkt signiert, wodurch die Eingabe-APK-Datei überschrieben wird.

--min-sdk-version <integer>

Das niedrigste Android-Framework-API-Level, das von apksigner verwendet wird, um zu bestätigen, dass die Signatur des APKs überprüft wird. Höhere Werte ermöglichen es dem Tool, beim Signieren der App stärkere Sicherheitsparameter zu verwenden, schränken aber die Verfügbarkeit des APKs auf Geräte mit neueren Android-Versionen ein. Standardmäßig verwendet apksigner den Wert des Attributs minSdkVersion aus der Manifestdatei der App.

--max-sdk-version <integer>

Das höchste Android-Framework-API-Level, das apksigner verwendet, um zu bestätigen, dass die Signatur des APK bestätigt wird. Standardmäßig wird im Tool die höchstmögliche API-Ebene verwendet.

--rotation-min-sdk-version <integer>

Das niedrigste API-Level, das für die Signatur des APKs mit dem rotierten Signaturschlüssel verwendet werden soll. Der ursprüngliche (nicht rotierte) Signaturschlüssel für das APK wird für alle vorherigen Plattformversionen verwendet. Standardmäßig werden rotierte Signaturschlüssel, die auf Geräten mit Android 13 (API‑Level 33) oder höher unterstützt werden, mit dem Signaturblock v3.1 verwendet.

Hinweis : Wenn Ihre App auf einem Gerät mit Android 12L (API-Level 32) oder niedriger mit einem rotierten Signaturschlüssel signiert wurde, müssen Sie --rotation-min-sdk-version 28 verwenden, um Ihre App weiterhin mit dem rotierten Signaturschlüssel für Android 9 (API-Level 28) zu signieren.

--v1-signing-enabled <true | false>

Gibt an, ob apksigner das angegebene APK-Paket mit dem herkömmlichen, JAR-basierten Signaturschema signiert. Standardmäßig verwendet das Tool die Werte von --min-sdk-version und --max-sdk-version, um zu entscheiden, wann dieses Signaturschema angewendet werden soll.

--v2-signing-enabled <true | false>

Gibt an, ob apksigner das angegebene APK-Paket mit dem APK-Signaturschema v2 signiert. Standardmäßig verwendet das Tool die Werte von --min-sdk-version und --max-sdk-version, um zu entscheiden, wann dieses Signaturschema angewendet werden soll.

--v3-signing-enabled <true | false>

Gibt an, ob apksigner das angegebene APK-Paket mit dem APK-Signaturschema v3 signiert. Standardmäßig verwendet das Tool die Werte von --min-sdk-version und --max-sdk-version, um zu entscheiden, wann dieses Signaturschema angewendet werden soll.

--v4-signing-enabled <true | false | only>

Bestimmt, ob apksigner das angegebene APK-Paket mit dem APK-Signaturschema v4 signiert. Bei diesem Schema wird eine Signatur in einer separaten Datei (apk-name.apk.idsig) erstellt. Wenn true und das APK nicht signiert sind, wird basierend auf den Werten von --min-sdk-version und --max-sdk-version eine v2- oder v3-Signatur generiert. Mit dem Befehl wird dann die Datei .idsig basierend auf dem Inhalt des signierten APK erstellt.

Verwenden Sie only, um nur die v4-Signatur zu generieren, ohne das APK und alle Signaturen zu ändern, die es vor dem Aufruf hatte. only schlägt fehl, wenn das APK noch keine v2- oder v3-Signatur hat oder wenn für die Signatur ein anderer Schlüssel verwendet wurde als der, der für den aktuellen Aufruf angegeben wurde.

Standardmäßig verwendet das Tool die Werte von --min-sdk-version und --max-sdk-version, um zu entscheiden, wann dieses Signaturschema angewendet werden soll.

-v, --verbose

Ausführlichen Ausgabemodus verwenden.

Optionen pro Unterzeichner

Mit den folgenden Optionen wird die Konfiguration eines bestimmten Unterzeichners angegeben. Diese Optionen sind nicht erforderlich, wenn Sie Ihre App nur mit einem Signierer signieren.

--next-signer <signer-options>

Wird verwendet, um für jeden Unterzeichner unterschiedliche allgemeine Optionen anzugeben.

--v1-signer-name <basename>

Der Basisname für die Dateien, aus denen die JAR-basierte Signatur für den aktuellen Unterzeichner besteht. Standardmäßig verwendet apksigner den Schlüsselalias des KeyStore oder den Basenamen der Schlüsseldatei für diesen Unterzeichner.

Schlüssel- und Zertifikatsoptionen

Mit den folgenden Optionen werden der private Schlüssel und das Zertifikat des Unterzeichners angegeben:

--ks <filename>

Der private Schlüssel und die Zertifikatskette des Unterzeichners befinden sich in der angegebenen Java-basierten KeyStore-Datei. Wenn der Dateiname auf "NONE" festgelegt ist, muss für den KeyStore, der den Schlüssel und das Zertifikat enthält, keine Datei angegeben werden. Das ist bei einigen PKCS #11-KeyStores der Fall.

--ks-key-alias <alias>

Der Name des Alias, der den privaten Schlüssel und die Zertifikatsdaten des Unterzeichners im KeyStore darstellt. Wenn der mit dem Unterzeichner verknüpfte KeyStore mehrere Schlüssel enthält, müssen Sie diese Option angeben.

--ks-pass <input-format>

Das Passwort für den KeyStore, der den privaten Schlüssel und das Zertifikat des Signaturgebers enthält. Sie müssen ein Passwort angeben, um einen KeyStore zu öffnen. Das apksigner-Tool unterstützt die folgenden Formate:

• pass:<password>: Das Passwort wird inline mit dem Rest des apksigner sign-Befehls angegeben.
• env:<name>: Das Passwort wird in der angegebenen Umgebungsvariable gespeichert.
• file:<filename>: Das Passwort wird als einzelne Zeile in der angegebenen Datei gespeichert.
• stdin: Das Passwort wird als einzelne Zeile im Standardeingabestream angegeben. Dies ist das Standardverhalten für --ks-pass.

Hinweis : Wenn Sie mehrere Passwörter in derselben Datei angeben, müssen Sie sie in separaten Zeilen eingeben. Das apksigner-Tool ordnet Passwörter den Unterzeichnern eines APKs in der Reihenfolge zu, in der Sie die Unterzeichner angeben. Wenn Sie zwei Passwörter für einen Unterzeichner angegeben haben, interpretiert apksigner das erste Passwort als das KeyStore-Passwort und das zweite als das Schlüsselpasswort.

--pass-encoding <charset>

Enthält die angegebenen Zeichencodierungen, z. B. ibm437 oder utf-8, wenn versucht wird, Passwörter mit Nicht-ASCII-Zeichen zu verarbeiten.

Keytool verschlüsselt Keystores häufig, indem das Passwort mit dem Standardzeichensatz der Konsole konvertiert wird. Standardmäßig versucht apksigner, die Entschlüsselung mit verschiedenen Formen des Passworts durchzuführen:

Die Unicode-Form

Das Formular, das mit dem JVM-Standardzeichensatz codiert wurde

In Java 8 und älter wird das Formular mit dem Standardzeichensatz der Konsole codiert.

Unter Java 9 kann apksigner das Zeichensatz der Konsole nicht erkennen. Möglicherweise müssen Sie --pass-encoding angeben, wenn ein Nicht-ASCII-Passwort verwendet wird. Möglicherweise müssen Sie diese Option auch für Schlüsselspeicher angeben, die mit „keytool“ auf einem anderen Betriebssystem oder in einem anderen Gebietsschema erstellt wurden.

--key-pass <input-format>

Das Passwort für den privaten Schlüssel des Unterzeichners, das erforderlich ist, wenn der private Schlüssel passwortgeschützt ist. Das apksigner-Tool unterstützt die folgenden Formate:

• pass:<password>: Das Passwort wird inline mit dem Rest des apksigner sign-Befehls angegeben.
• env:<name>: Das Passwort wird in der angegebenen Umgebungsvariable gespeichert.
• file:<filename>: Das Passwort wird als einzelne Zeile in der angegebenen Datei gespeichert.
• stdin: Das Passwort wird als einzelne Zeile im Standardeingabestream angegeben. Dies ist das Standardverhalten für --key-pass.

--ks-type <algorithm>

Der Typ oder Algorithmus, der dem KeyStore zugeordnet ist, der den privaten Schlüssel und das Zertifikat des Unterzeichners enthält. Standardmäßig wird für apksigner der Typ verwendet, der als keystore.type-Konstante in der Datei mit Sicherheitseigenschaften definiert ist.

--ks-provider-name <name>

Der Name des JCA-Anbieters, der beim Anfordern der KeyStore-Implementierung des Unterzeichners verwendet werden soll. Standardmäßig verwendet apksigner den Anbieter mit der höchsten Priorität.

--ks-provider-class <class-name>

Der voll qualifizierte Klassenname des JCA-Anbieters, der beim Anfordern der KeyStore-Implementierung des Unterzeichners verwendet werden soll. Diese Option ist eine Alternative zu --ks-provider-name. Standardmäßig verwendet apksigner den mit der Option --ks-provider-name angegebenen Anbieter.

--ks-provider-arg <value>

Ein Stringwert, der als Argument für den Konstruktor der JCA-Provider-Klasse übergeben werden soll. Die Klasse selbst wird mit der Option --ks-provider-class definiert. Standardmäßig verwendet apksigner den Konstruktor der Klasse ohne Argumente.

--key <filename>

Der Name der Datei, die den privaten Schlüssel des Signaturgebers enthält. Diese Datei muss das PKCS #8-DER-Format verwenden. Wenn der Schlüssel durch ein Passwort geschützt ist, fordert apksigner das Passwort über die Standardeingabe an, sofern Sie mit der Option --key-pass kein anderes Eingabeformat angeben.

--cert <filename>

Der Name der Datei, die die Zertifikatkette des Unterzeichners enthält. Diese Datei muss das X.509-PEM- oder DER-Format haben.

Befehl bestätigen

Der Befehl apksigner bietet folgende Optionen.

--print-certs

Informationen zu den Signaturzertifikaten der APK anzeigen.

--print-certs-pem

Informationen zu den Signaturzertifikaten des APKs anzeigen und die PEM-Codierung jedes Signaturzertifikats in stdout ausgeben.

--min-sdk-version <integer>

Das niedrigste Android-Framework-API-Level, das von apksigner verwendet wird, um zu bestätigen, dass die Signatur des APKs überprüft wird. Höhere Werte ermöglichen es dem Tool, beim Signieren der App stärkere Sicherheitsparameter zu verwenden, schränken aber die Verfügbarkeit des APKs auf Geräte mit neueren Android-Versionen ein. Standardmäßig verwendet apksigner den Wert des Attributs minSdkVersion aus der Manifestdatei der App.

--max-sdk-version <integer>

Das höchste Android-Framework-API-Level, das apksigner verwendet, um zu bestätigen, dass die Signatur des APKs überprüft wird. Standardmäßig wird im Tool die höchstmögliche API-Ebene verwendet.

-v, --verbose

Ausführlichen Ausgabemodus verwenden.

-Werr

Warnungen als Fehler behandeln

Beispiele

Nachfolgend finden Sie Beispiele für die Verwendung von apksigner.

APK signieren

Signieren Sie ein APK mit release.jks, dem einzigen Schlüssel im KeyStore:

$ apksigner sign --ks release.jks app.apk

So signieren Sie ein APK mit einem privaten Schlüssel und einem Zertifikat, die als separate Dateien gespeichert sind:

$ apksigner sign --key release.pk8 --cert release.x509.pem app.apk

So signieren Sie ein APK mit zwei Schlüsseln:

$ apksigner sign --ks first-release-key.jks --next-signer --ks second-release-key.jks app.apk

So signieren Sie ein APK mit einem rotierten Signaturschlüssel und der SDK-Version 28 oder höher als Ziel:

$ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage app.apk \
  --rotation-min-sdk-version 28

So signieren Sie ein APK mit einem rotierten Signaturschlüssel und der SDK-Version 33 oder höher als Ziel:

$ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage app.apk

Signatur eines APK prüfen

Prüfen Sie, ob die Signaturen des APKs auf allen Android-Plattformen, die das APK unterstützt, als gültig bestätigt werden sollen:

$ apksigner verify app.apk

Prüfen Sie, ob die Signaturen des APKs unter Android 4.0.3 (API‑Level 15) und höher als gültig bestätigt werden sollen:

$ apksigner verify --min-sdk-version 15 app.apk

Signaturschlüssel rotieren

Aktivieren Sie eine Signaturzertifikatslinie, die die Schlüsselrotation unterstützt:

$ apksigner rotate --out /path/to/new/file --old-signer \
    --ks release.jks --new-signer --ks release2.jks

Rotieren Sie Ihre Signaturschlüssel noch einmal:

$ apksigner rotate --in /path/to/existing/lineage \
  --out /path/to/new/file --old-signer --ks release2.jks \
  --new-signer --ks release3.jks