apksigner

Narzędzie apksigner dostępne w wersji 24.0.3 lub nowszej SDK Build Tools pozwala podpisywać pliki APK i potwierdzać, że Podpis pliku APK zostanie zweryfikowany we wszystkich wersjach Androida platformy obsługiwanej przez ten plik APK.

Na tej stronie znajdziesz krótki przewodnik po korzystaniu z jest narzędziem dla wielu opcji wiersza poleceń, obsługiwanych przez narzędzie. Aby uzyskać pełniejszy opis tego, Do podpisywania plików APK służy narzędzie apksigner. Więcej informacji znajdziesz w artykule Podpisywanie aplikacji.

Uwaga: jeśli podpiszesz pakiet APK za pomocą usługi apksigner i wprowadzisz dalsze zmiany w pakiecie APK, podpis pliku APK zostanie unieważniony. Jeśli używasz zipalign, aby wyrównać pliku APK, skorzystaj z niego przed jego podpisaniem.

Wykorzystanie

Podpisz plik APK

Składnia używana do podpisywania pakietu APK za pomocą narzędzia apksigner to następujące: 

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

Podczas podpisywania pliku APK za pomocą narzędzia apksigner musisz dostarczyć klucz prywatny i certyfikat osoby podpisującej. Możesz uwzględnić te informacje w: na dwa sposoby:

  • Określ plik KeyStore za pomocą opcji --ks.
  • Plik klucza prywatnego i plik certyfikatu określ oddzielnie za pomocą opcje --key i --cert. plik z kluczem prywatnym musi mieć format PKCS #8, a plik certyfikatu użyć formatu X.509.

Zwykle podpisuje się plik APK przy pomocy tylko jednego sygnatariusza. W razie potrzeby podpisz plik APK przez wielu sygnatariuszy, użyj opcji --next-signer aby rozdzielić opcje ogólne na zastosuj do każdego sygnatariusza: 

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

Sprawdzanie podpisu pakietu APK

Składnia potwierdzająca pomyślną weryfikację podpisu pakietu APK na obsługiwanych platformach wygląda tak: 

apksigner verify [options] app-name.apk

Wykonaj rotację kluczy podpisywania

Składnia rotacji historii pochodzenia certyfikatu podpisywania lub nowa sekwencja będzie wyglądać tak:

$ 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ższe listy zawierają zestaw opcji dla każdego polecenia, którego Narzędzie apksigner obsługuje.

Podpisz polecenie

Polecenie podpisywania apksigner zawiera następujące opcje.

Opcje ogólne

Te opcje określają podstawowe ustawienia, które mają być stosowane do osoby podpisującej:

--out <apk-filename>
Lokalizacja, w której chcesz zapisać podpisany pakiet APK. Jeśli nie, jednoznacznie, podpisano pakiet APK, co zastępuje wejściowy plik APK.
--min-sdk-version <integer>
Najniższy poziom interfejsu API platformy Android, którego używa apksigner do upewnij się, że podpis pliku APK zostanie zweryfikowany. Wyższe wartości umożliwiają do używania silniejszych parametrów zabezpieczeń podczas podpisywania aplikacji, ale ograniczaj na urządzeniach z nowszymi wersjami Androida. Domyślnie apksigner używa wartości atrybutu minSdkVersion z pliku manifestu aplikacji.
--max-sdk-version <integer>
Najwyższy poziom interfejsu Android Framework API, z którego korzysta apksigner aby potwierdzić, że podpis pliku APK zostanie zweryfikowany. Domyślnie narzędzie korzysta z najwyższego możliwego poziomu interfejsu API.
--rotation-min-sdk-version <integer>
Najniższy poziom interfejsu API pod kątem rotacji podpisywania pliku APK powinien być używany do wygenerowania podpisu pakietu APK. oryginalny (nierotacyjny) klucz podpisywania dla pliku APK będzie używany do wszystkich z poprzednimi wersjami platformy. Domyślnie poddane rotacji kluczy podpisywania, które są obsługiwane na urządzeniach z Androidem 13; (poziom interfejsu API 33) lub nowszego są używane z blokiem podpisywania w wersji 3.1.

Uwaga: jeśli Twoja aplikacja została podpisana w ramach rotacji rotacji na urządzeniu z Androidem 12L (poziom interfejsu API 32) lub niższym, musi używać --rotation-min-sdk-version 28, aby kontynuować podpisywanie aplikacji przy użyciu zmienionego klucza podpisywania na Androida 9 (poziom interfejsu API 28).

--v1-signing-enabled <true | false>
Określa, czy apksigner podpisuje dany pakiet APK w ramach 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 podpis oszustw.
--v2-signing-enabled <true | false>
Określa, czy apksigner podpisuje dany pakiet APK przy użyciu pakietu APK Schemat podpisu w wersji 2. Domyślnie narzędzie używa wartości --min-sdk-version i --max-sdk-version dokonają decyzji kiedy stosować ten schemat podpisu.
--v3-signing-enabled <true | false>
Określa, czy apksigner podpisuje dany pakiet APK przy użyciu pakietu APK Schemat podpisu w wersji 3. Domyślnie narzędzie używa wartości --min-sdk-version i --max-sdk-version dokonają decyzji kiedy stosować ten schemat podpisu.
--v4-signing-enabled <true | false | only>

Określa, czy apksigner podpisuje dany pakiet APK przy użyciu pliku APK Schemat podpisu w wersji 4. Ten schemat tworzy podpis w osobnym pliku (apk-name.apk.idsig). Jeśli true i plik APK nie są podpisane, wymagany jest podpis w wersji 2 lub 3. jest generowany na podstawie wartości --min-sdk-version oraz --max-sdk-version To polecenie generuje następnie .idsig na podstawie zawartości podpisanego pakietu APK.

Użyj pola only, aby wygenerować tylko wersję 4 podpis bez modyfikacji pliku APK ani żadnych podpisów jaki miał przed wywołaniem. only kończy się niepowodzeniem, jeśli plik APK nie ma już podpis w wersji 2 lub 3 albo jeśli podpis używa innego klucza niż podany na potrzeby bieżącego wywołania.

Domyślnie narzędzie używa wartości --min-sdk-version i --max-sdk-version dokonają decyzji kiedy stosować ten schemat podpisu.

-v, --verbose
Użyj trybu szczegółowych danych wyjściowych.

Opcje dla poszczególnych sygnatariuszy

Poniższe opcje określają konfigurację konkretnego sygnatariusza. Te opcje nie są wymagane, jeśli podpisujesz aplikację tylko przy użyciu 1 sygnatariusza.

--next-signer <signer-options>
Służy do określania różnych ogólnych opcji dla każdego sygnatariusza.
--v1-signer-name <basename>
Podstawowa nazwa dla plików zawierających podpis oparty na JAR dla pliku obecnego sygnatariusza. Domyślnie apksigner używa aliasu klucza magazyn kluczy lub nazwę bazową 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 podpisującego znajdują się w określonym Plik KeyStore w Javie. Jeśli nazwa pliku jest ustawiona na "NONE", magazyn kluczy zawierający klucz i certyfikat nie wymaga pliku co dotyczy niektórych magazynów kluczy PKCS #11.
--ks-key-alias <alias>
nazwa aliasu, który reprezentuje klucz prywatny osoby podpisującej; i danych certyfikatów w magazynie kluczy. Jeśli magazyn kluczy powiązany z podpisujący zawiera wiele kluczy, musisz określić tę opcję.
--ks-pass <input-format>

hasło do magazynu kluczy zawierającego klucz prywatny osoby podpisującej, certyfikat. Aby otworzyć magazyn kluczy, musisz podać hasło. Narzędzie apksigner obsługuje te formaty:

  • pass:<password> – hasło zostało podane w tekście w pozostałej części polecenia apksigner sign.
  • env:<name> – hasło jest zapisane w podanym zmiennej środowiskowej.
  • file:<filename> – hasło jest przechowywane jako w danym pliku.
  • stdin – hasło jest podawane w pojedynczym wierszu w ze standardowym strumieniem danych wejściowych. Jest to domyślne działanie w przypadku --ks-pass

Uwaga: jeśli podasz kilka haseł musisz wpisać je w osobnych wierszach. Narzędzie apksigner wiąże hasła z sygnatariuszami pakietu APK na podstawie kolejności, określić osoby podpisujące. Jeśli podasz 2 hasła dla osoby podpisującej, apksigner interpretuje pierwsze hasło jako magazyn kluczy a drugie – jako hasło klucza.

--pass-encoding <charset>
Zawiera określone kodowanie znaków, takie jak ibm437 lub utf-8, gdy próbujesz obsługi haseł zawierających znaki spoza zestawu ASCII.

Narzędzie Keytool często szyfruje magazyny kluczy, konwertując hasło za pomocą domyślnego ustawienia konsoli . Domyślnie apksigner próbuje odszyfrować dane, używając kilku form funkcji hasło:

  • Formularz Unicode
  • Formularz zakodowany przy użyciu domyślnego zestawu znaków JVM
  • W Javie 8 i starszych wersjach forma zakodowana z użyciem domyślnego zestawu znaków konsoli

    • W Javie 9 interfejs apksigner nie może wykryć zestawu znaków konsoli. Może być konieczne określenie atrybutu --pass-encoding, gdy używane jest hasło inne niż ASCII. Konieczne może być również określenie tej opcji w KeyStores, narzędzie keytool utworzone w innym systemie operacyjnym lub w innym języku.

    --key-pass <input-format>

    Hasło klucza prywatnego podpisującego, które jest wymagane, jeśli Klucz prywatny jest chroniony hasłem. Narzędzie apksigner obsługuje następujące formaty:

    • pass:<password> – hasło jest podawane w tekście w pozostałej części polecenia apksigner sign.
    • env:<name> – hasło jest zapisane w podanym zmiennej środowiskowej.
    • file:<filename> – hasło jest przechowywane jako w danym pliku.
    • stdin – hasło jest podawane w pojedynczym wierszu w ze standardowym strumieniem danych wejściowych. Jest to domyślne działanie w przypadku --key-pass
    --ks-type <algorithm>
    Typ lub algorytm powiązany z magazynem kluczy, który zawiera klucz prywatny i certyfikat osoby podpisującej. Domyślnie apksigner używa typu zdefiniowanego jako stała keystore.type w parametrze Właściwości zabezpieczeń.
    --ks-provider-name <name>
    Nazwa dostawcy JCA, która ma być używana podczas wysyłania żądania do magazynu kluczy podpisującego implementacji. Domyślnie apksigner używa o najwyższym priorytecie.
    --ks-provider-class <class-name>
    Pełna nazwa klasy dostawcy JCA, która ma być używana w żądaniach implementacji KeyStore osoby podpisującej. Ta opcja jest alternatywą dla --ks-provider-name. Domyślnie apksigner korzysta z dostawcy określonego za pomocą atrybutu --ks-provider-name .
    --ks-provider-arg <value>
    Wartość ciągu znaków do przekazania jako argument konstruktora JCA klasa dostawcy; klasa jest zdefiniowana za pomocą funkcji --ks-provider-class. Domyślnie apksigner korzysta z konstruktora klasy zero-argument.
    --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 wprowadzania danych chyba że określisz inny rodzaj formatu danych wejściowych za pomocą funkcji --key-pass.
    --cert <filename>
    Nazwa pliku zawierającego łańcuch certyfikatów osoby podpisującej. Ten musi być w formacie X.509 PEM lub DER.

    Sprawdź polecenie

    Polecenie apksigner weryfikacji zawiera następujące opcje.

    --print-certs
    Pokaż informacje o certyfikatach podpisywania pliku APK.
    --min-sdk-version <integer>
    Najniższy poziom interfejsu API platformy Android, którego używa apksigner do upewnij się, że podpis pliku APK zostanie zweryfikowany. Wyższe wartości umożliwiają do używania silniejszych parametrów zabezpieczeń podczas podpisywania aplikacji, ale ograniczaj na urządzeniach z nowszymi wersjami Androida. Domyślnie apksigner używa wartości atrybutu minSdkVersion z pliku manifestu aplikacji.
    --max-sdk-version <integer>
    Najwyższy poziom interfejsu Android Framework API, z którego korzysta apksigner aby potwierdzić, że podpis pliku APK zostanie zweryfikowany. Domyślnie narzędzie korzysta z 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 znajdziesz przykłady wykorzystania właściwości apksigner.

    Podpisz plik APK

    Podpisz plik APK przy użyciu polecenia release.jks, który jest jedynym kluczem w Magazyn kluczy: 

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

    Podpisz plik APK przy użyciu klucza prywatnego i certyfikatu przechowywanych jako osobne pliki: 

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

    Podpisz plik APK za pomocą 2 kluczy: 

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

    Podpisz plik APK przy użyciu rotacji klucza podpisywania i pakietu SDK w wersji 28 lub nowszej kierowanej 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 przy użyciu rotacji klucza podpisywania i rotacji pakietu SDK w wersji 33 lub nowszej: 

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

    Sprawdzanie podpisu pakietu APK

    Sprawdź, czy podpisy pakietu APK powinny być potwierdzone jako prawidłowe wszystkie platformy Androida obsługiwane przez plik APK: 

    $ apksigner verify app.apk

    Sprawdź, czy podpisy pakietu APK powinny być potwierdzone jako prawidłowe Android 4.0.3 (poziom interfejsu API 15) lub nowszy: 

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

    Wykonaj rotację kluczy podpisywania

    Włącz historię danych certyfikatu podpisywania, która obsługuje rotację kluczy:

    $ 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