Narzędzie apksigner
, dostępne w Narzędziach Android SDK Build Tools w wersji 24.0.3 lub nowszej, pozwala podpisywać pliki APK i potwierdzać, czy podpis pliku APK zostanie zweryfikowany we wszystkich wersjach platformy Androida obsługiwanych przez ten plik APK.
Ta strona zawiera krótki przewodnik na temat korzystania z narzędzia oraz informacje o różnych opcjach wiersza poleceń obsługiwanych przez to narzędzie. Pełny opis sposobu używania narzędzia apksigner
do podpisywania plików APK znajdziesz w artykule Podpisywanie aplikacji.
Uwaga: jeśli podpiszesz pakiet APK za pomocą apksigner
i wprowadzisz w nim dalsze zmiany, podpis pliku APK zostanie unieważniony.
Jeśli do dostosowania pliku APK używasz zipalign
, użyj go przed podpisaniem pliku APK.
Wykorzystanie
Podpisywanie pakietu APK
Składnia podpisywania pakietu APK za pomocą narzędzia apksigner
jest taka:
apksigner sign --ks keystore.jks | --key key.pk8 --cert cert.x509.pem [signer_options] app-name.apk
Gdy podpisujesz plik APK za pomocą narzędzia apksigner
, musisz podać klucz prywatny i certyfikat osoby podpisującej. Możesz dołączyć te informacje na 2 sposoby:
-
Określ plik KeyStore za pomocą opcji
--ks
. -
Określ oddzielnie plik klucza prywatnego i plik certyfikatu, używając odpowiednio opcji
--key
i--cert
. Plik klucza prywatnego musi mieć format PKCS8, a plik certyfikatu musi mieć format X.509.
Zwykle plik APK jest podpisywany tylko przez jedną osobę podpisującą. Jeśli musisz podpisać plik APK przy użyciu wielu sygnatariuszy, użyj opcji --next-signer
, aby oddzielić zestaw ogólnych opcji, które będą stosowane do poszczególnych sygnatariuszy:
apksigner sign [signer_1_options] --next-signer [signer_2_options] app-name.apk
Sprawdzanie podpisu pliku APK
Składnia potwierdzająca pomyślną weryfikację podpisu pakietu APK na obsługiwanych platformach jest taka:
apksigner verify [options] app-name.apk
Wykonaj rotację kluczy podpisywania
Składnia rotacji historii certyfikatu podpisywania lub nowej sekwencji podpisów jest taka:
$ apksigner rotate --in /path/to/existing/lineage \ --out /path/to/new/file \ --old-signer --ks old-signer-jks \ --new-signer --ks new-signer-jks
Opcje
Poniżej znajdziesz zestaw opcji każdego polecenia obsługiwanego przez narzędzie apksigner
.
Podpisz polecenie
Polecenie podpisu apksigner
zawiera następujące opcje.
Opcje ogólne
Te opcje określają podstawowe ustawienia, które należy zastosować do osoby podpisującej:
--out <apk-filename>
- Lokalizacja, w której chcesz zapisać podpisany plik APK. Jeśli ta opcja nie zostanie podana wprost, pakiet APK zostanie podpisany, co spowoduje zastąpienie wejściowego pliku APK.
--min-sdk-version <integer>
- Najniższy poziom interfejsu API platformy Androida, którego
apksigner
używa do potwierdzania podpisu pliku APK. Wyższe wartości pozwalają narzędziu na użycie silniejszych parametrów zabezpieczeń podczas podpisywania aplikacji, ale ogranicza dostępność pliku APK do urządzeń z najnowszymi wersjami Androida. Domyślnieapksigner
używa wartości atrybutuminSdkVersion
z pliku manifestu aplikacji. --max-sdk-version <integer>
- Najwyższy poziom interfejsu API platformy Androida, którego
apksigner
używa do potwierdzania podpisu pliku APK. Domyślnie narzędzie używa najwyższego możliwego poziomu interfejsu API. --rotation-min-sdk-version <integer>
- Najniższy poziom interfejsu API, z którego powinien korzystać poddany rotacji klucz podpisywania APK do wygenerowania podpisu pakietu APK. We wszystkich poprzednich wersjach platformy będzie używany oryginalny (bez rotacji) klucz podpisywania pliku APK. Domyślnie rotowane klucze podpisywania, które są obsługiwane na urządzeniach z Androidem 13 (poziom interfejsu API 33) lub nowszym, są używane z blokiem podpisywania w wersji 3.1.
--v1-signing-enabled <true | false>
- Określa, czy
apksigner
podpisuje dany pakiet APK za pomocą tradycyjnego schematu podpisywania opartego na JAR. Domyślnie narzędzie używa wartości--min-sdk-version
i--max-sdk-version
, aby zdecydować, kiedy zastosować ten schemat podpisu. --v2-signing-enabled <true | false>
- Określa, czy
apksigner
podpisuje dany pakiet APK za pomocą schematu podpisu pliku APK w wersji 2. Domyślnie narzędzie używa wartości--min-sdk-version
i--max-sdk-version
, aby zdecydować, kiedy zastosować ten schemat podpisu. --v3-signing-enabled <true | false>
- Określa, czy
apksigner
podpisuje dany pakiet APK za pomocą schematu podpisu pliku APK w wersji 3. Domyślnie narzędzie używa wartości--min-sdk-version
i--max-sdk-version
, aby zdecydować, kiedy zastosować ten schemat podpisu. --v4-signing-enabled <true | false | only>
-
Określa, czy
apksigner
podpisuje dany pakiet APK za pomocą schematu podpisu pliku APK w wersji 4. Ten schemat tworzy podpis w osobnym pliku (apk-name.apk.idsig
). Jeślitrue
i plik APK nie są podpisane, podpis w wersji 2 lub 3 jest generowany na podstawie wartości--min-sdk-version
i--max-sdk-version
. Następnie polecenie tworzy plik.idsig
na podstawie treści podpisanego pakietu APK.Użyj
only
, aby wygenerować tylko podpis w wersji 4 bez modyfikowania pliku APK i podpisów, które miał przed wywołaniem.only
kończy się niepowodzeniem, jeśli plik APK nie ma jeszcze podpisu w wersji 2 lub 3 albo podpis używa innego klucza niż ten podany do bieżącego wywołania.Domyślnie narzędzie używa wartości
--min-sdk-version
i--max-sdk-version
, aby zdecydować, kiedy zastosować ten schemat podpisu. -v
,--verbose
- Użyj trybu szczegółowych danych wyjściowych.
Uwaga: jeśli Twoja aplikacja została podpisana rotowanym kluczem podpisywania na urządzeniu z Androidem 12L (poziom interfejsu API 32) lub niższym, musisz użyć --rotation-min-sdk-version 28
, aby nadal podpisywać aplikację za pomocą rotacji klucza podpisywania dla Androida 9 (poziom interfejsu API 28).
Opcje dla podpisujących
Poniższe opcje określają konfigurację konkretnej osoby podpisującej. Te opcje nie są konieczne, jeśli podpisujesz aplikację tylko za pomocą jednego sygnatariusza.
--next-signer <signer-options>
- Używane do określania różnych ogólnych opcji dla każdego sygnatariusza.
--v1-signer-name <basename>
-
Podstawowa nazwa plików składających się na podpis oparty na JAR dla bieżącego podpisującego. Domyślnie
apksigner
używa aliasu klucza magazynu kluczy lub nazwy bazowej pliku klucza dla tego podpisującego.
Opcje klucza i certyfikatu
Te opcje określają klucz prywatny i certyfikat osoby podpisującej:
--ks <filename>
- Klucz prywatny i łańcuch certyfikatów osoby podpisującej znajdują się w danym pliku KeyStore opartym na Javie. Jeśli nazwa pliku jest ustawiona na
"NONE"
, magazyn kluczy zawierający klucz i certyfikat nie wymaga określonego pliku. Dotyczy to niektórych magazynów kluczy PKCS #11. --ks-key-alias <alias>
- Nazwa aliasu reprezentującego klucz prywatny osoby podpisującej i dane certyfikatu w magazynie kluczy. Jeśli magazyn kluczy powiązany z osobą podpisującą zawiera wiele kluczy, musisz określić tę opcję.
--ks-pass <input-format>
-
Hasło do magazynu kluczy, który zawiera klucz prywatny i certyfikat osoby podpisującej. Aby otworzyć magazyn kluczy, musisz podać hasło. Narzędzie
apksigner
obsługuje te formaty:-
pass:<password>
– hasło podane w tekście w pozostałej części poleceniaapksigner sign
. -
env:<name>
– hasło jest przechowywane w podanej zmiennej środowiskowej. -
file:<filename>
– hasło jest przechowywane w pojedynczym wierszu w pliku. -
stdin
– hasło jest podawane w postaci pojedynczego wiersza w standardowym strumieniu danych wejściowych. Jest to domyślne zachowanie--ks-pass
.
Uwaga: jeśli w tym samym pliku umieścisz kilka haseł, podaj je w oddzielnych wierszach. Narzędzie
apksigner
łączy hasła z sygnatariuszami pakietu APK na podstawie ich kolejności, w jakiej je sygnatujesz. Jeśli dla osoby podpisującej podasz 2 hasła,apksigner
zinterpretuje pierwsze hasło jako hasło magazynu kluczy, a drugie jako hasło klucza. -
--pass-encoding <charset>
- Uwzględnia określone kodowanie znaków, takie jak
ibm437
lubutf-8
, przy próbie obsługi haseł zawierających znaki spoza zestawu ASCII.Keytool często szyfruje magazyny kluczy, konwertując hasło za pomocą domyślnego zestawu znaków konsoli. Domyślnie
apksigner
próbuje odszyfrować dane przy użyciu kilku form hasła:- Formularz Unicode
- Formularz zakodowany z użyciem domyślnego zestawu znaków JVM
- W Javie 8 i starszych formularz zakodowany z użyciem domyślnego zestawu znaków konsoli
W środowisku Java 9
apksigner
nie może wykryć zestawu znaków konsoli. Jeśli używane jest hasło spoza zestawu ASCII, może być konieczne podanie--pass-encoding
. Może być też konieczne określenie tej opcji w magazynach kluczy, które narzędzie Keytool utworzyło w innym systemie operacyjnym lub w innym języku. --key-pass <input-format>
-
Hasło klucza prywatnego osoby podpisującej, które jest potrzebne, jeśli klucz prywatny jest chroniony hasłem. Narzędzie
apksigner
obsługuje te formaty:-
pass:<password>
– hasło jest podawane w tekście w pozostałej części poleceniaapksigner sign
. -
env:<name>
– hasło jest przechowywane w podanej zmiennej środowiskowej. -
file:<filename>
– hasło jest przechowywane w pojedynczym wierszu w pliku. -
stdin
– hasło jest podawane w postaci pojedynczego wiersza w standardowym strumieniu danych wejściowych. Jest to domyślne zachowanie--key-pass
.
-
--ks-type <algorithm>
- Typ lub algorytm powiązany z magazynem kluczy zawierającym klucz prywatny i certyfikat osoby podpisującej. Domyślnie
apksigner
używa typu zdefiniowanego jako stałakeystore.type
w pliku właściwości zabezpieczeń. --ks-provider-name <name>
- Nazwa dostawcy JCA używanego w przypadku żądania implementacji magazynu kluczy osoby podpisującej. Domyślnie
apksigner
używa dostawcy o najwyższym priorytecie. --ks-provider-class <class-name>
- Pełna i jednoznaczna nazwa klasy dostawcy JCA używana w przypadku żądania implementacji magazynu kluczy osoby podpisującej. Ta opcja jest alternatywą dla
--ks-provider-name
. Domyślnieapksigner
używa dostawcy określonego za pomocą opcji--ks-provider-name
. --ks-provider-arg <value>
- Wartość ciągu znaków, który ma być przekazywany jako argument dla konstruktora klasy dostawcy JCA. Sama klasa jest definiowana za pomocą opcji
--ks-provider-class
. Domyślnieapksigner
używa konstruktora klasy bez argumentów. --key <filename>
- Nazwa pliku zawierającego klucz prywatny osoby podpisującej. Ten plik musi mieć format PKCS #8 DER. Jeśli klucz jest chroniony hasłem,
apksigner
prosi o podanie hasła przy użyciu standardowego sposobu wprowadzania tekstu, chyba że określisz inny format wprowadzania za pomocą opcji--key-pass
. --cert <filename>
- Nazwa pliku zawierającego łańcuch certyfikatów osoby podpisującej. Ten plik musi być w formacie X.509 PEM lub DER.
Zweryfikuj polecenie
Polecenie weryfikacji apksigner
zawiera te opcje.
--print-certs
- Pokaż informacje o certyfikatach podpisywania pakietu APK.
--min-sdk-version <integer>
- Najniższy poziom interfejsu API platformy Androida, którego
apksigner
używa do potwierdzania podpisu pliku APK. Wyższe wartości pozwalają narzędziu na użycie silniejszych parametrów zabezpieczeń podczas podpisywania aplikacji, ale ogranicza dostępność pliku APK do urządzeń z najnowszymi wersjami Androida. Domyślnieapksigner
używa wartości atrybutuminSdkVersion
z pliku manifestu aplikacji. --max-sdk-version <integer>
- Najwyższy poziom interfejsu API platformy Androida, którego
apksigner
używa do potwierdzania podpisu pliku APK. Domyślnie narzędzie używa najwyższego możliwego poziomu interfejsu API. -v
,--verbose
- Użyj trybu szczegółowych danych wyjściowych.
-Werr
- Traktuj ostrzeżenia jako błędy.
Przykłady
Poniżej podano przykłady z użyciem funkcji apksigner
.
Podpisywanie pakietu APK
Podpisz plik APK przy użyciu release.jks
, który jest jedynym kluczem w KeyStore:
$ apksigner sign --ks release.jks app.apk
Podpisz plik APK za pomocą klucza prywatnego i certyfikatu przechowywanych w osobnych plikach:
$ apksigner sign --key release.pk8 --cert release.x509.pem app.apk
Podpisz plik APK, używając 2 kluczy:
$ apksigner sign --ks first-release-key.jks --next-signer --ks second-release-key.jks app.apk
Podpisz plik APK z wykorzystaniem rotacji klucza podpisywania i pakietu SDK w wersji 28 lub nowszej kierowanego na rotację:
$ apksigner sign --ks release.jks --next-signer --ks release2.jks \ --lineage /path/to/signing/history/lineage app.apk \ --rotation-min-sdk-version 28
Podpisz plik APK, używając rotacji klucza podpisywania i pakietu SDK w wersji 33 lub nowszej kierowanego na rotację:
$ apksigner sign --ks release.jks --next-signer --ks release2.jks \ --lineage /path/to/signing/history/lineage app.apk
Sprawdzanie podpisu pliku APK
Sprawdź, czy podpisy w pliku APK powinny zostać potwierdzone jako prawidłowe na wszystkich platformach Androida, które obsługuje ten plik:
$ apksigner verify app.apk
Sprawdź, czy podpisy pliku APK powinny zostać potwierdzone na Androidzie 4.0.3 (poziom interfejsu API 15) i nowszych:
$ apksigner verify --min-sdk-version 15 app.apk
Wykonaj rotację kluczy podpisywania
Włącz historię danych certyfikatu podpisywania, która obsługuje rotację klucza:
$ apksigner rotate --out /path/to/new/file --old-signer \ --ks release.jks --new-signer --ks release2.jks
Ponownie wykonaj rotację kluczy podpisywania:
$ apksigner rotate --in /path/to/existing/lineage \ --out /path/to/new/file --old-signer --ks release2.jks \ --new-signer --ks release3.jks