apksigner

Android SDK Derleme Araçlarının 24.0.3 düzeltme sürümünde ve sonraki sürümlerinde kullanılabilen apksigner aracı, APK'ları imzalamanızı ve bir APK'nın imzasının söz konusu APK tarafından desteklenen tüm Android platform sürümlerinde başarılı bir şekilde doğrulanacağını onaylamanızı sağlar.

Bu sayfada, aracın kullanımına ilişkin kısa bir kılavuz sunulmakta ve aracın desteklediği farklı komut satırı seçenekleri için referans işlevi gösterilmektedir. APK'larınızı imzalamak için apksigner aracının nasıl kullanıldığıyla ilgili daha kapsamlı bir açıklama için Uygulamanızı imzalama konusuna bakın.

Dikkat: APK'nızı apksigner kullanarak imzalar ve APK'da başka değişiklikler yaparsanız APK'nın imzası geçersiz kılınır. APK'nızı uyumlu hale getirmek için zipalign kullanıyorsanız APK'yı imzalamadan önce bunu kullanın.

Kullanım

Bir APK imzalayın

apksigner aracını kullanarak bir APK imzalamak için kullanılacak söz dizimi aşağıdaki gibidir:

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

apksigner aracını kullanarak bir APK'yı imzaladığınızda imzalayanın özel anahtarını ve sertifikasını sağlamanız gerekir. Bu bilgileri iki şekilde ekleyebilirsiniz:

  • --ks seçeneğini kullanarak bir KeyStore dosyası belirtin.
  • Özel anahtar dosyasını ve sertifika dosyasını sırasıyla --key ve --cert seçeneklerini kullanarak ayrı ayrı belirtin. Özel anahtar dosyası PKCS #8 biçimini, sertifika dosyası ise X.509 biçimini kullanmalıdır.

APK'ları genellikle yalnızca tek bir imzalayanla imzalarsınız. Bir APK'yı birden fazla imzalayan kullanarak imzalamanız gerekiyorsa her bir imzalayana uygulanacak genel seçenekler grubunu ayırmak için --next-signer seçeneğini kullanın:

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

APK'nın imzasını doğrulama

Desteklenen platformlarda bir APK'nın imzasının başarılı bir şekilde doğrulanmasını onaylamak için kullanılan söz dizimi aşağıdaki gibidir:

apksigner verify [options] app-name.apk

İmzalama anahtarlarını değiştirme

İmzalama sertifikası sınıfı veya yeni imza dizisi döndürmeyle ilgili söz dizimi aşağıdaki gibidir:

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

Seçenekler

Aşağıdaki listeler, apksigner aracının desteklediği her bir komut için seçenek grubunu içerir.

İmzala komutu

apksigner işareti komutunda aşağıdaki seçenekler bulunur.

Genel seçenekler

Aşağıdaki seçenekler, imzalayana uygulanacak temel ayarları belirtir:

--out <apk-filename>
İmzalanmış APK'yı kaydetmek istediğiniz konum. Bu seçenek açık bir şekilde sağlanmazsa APK paketi imzalanır ve giriş APK dosyasının üzerine yazılır.
--min-sdk-version <integer>
APK'nın imzasının doğrulanacağını onaylamak için apksigner tarafından kullanılan en düşük Android Framework API düzeyi. Daha yüksek değerler, aracın uygulamayı imzalarken daha güçlü güvenlik parametreleri kullanmasına izin verir ancak APK'nın kullanılabilirliğini, Android'in daha yeni sürümlerini çalıştıran cihazlarla sınırlandırır. apksigner, varsayılan olarak uygulamanın manifest dosyasındaki minSdkVersion özelliğinin değerini kullanır.
--max-sdk-version <integer>
APK'nın imzasının doğrulanacağını onaylamak için apksigner tarafından kullanılan en yüksek Android Framework API düzeyi. Varsayılan olarak araç mümkün olan en yüksek API düzeyini kullanır.
--rotation-min-sdk-version <integer>
APK'nın döndürülmüş imzalama anahtarının, APK'nın imzasını oluşturmak için kullanması gereken en düşük API düzeyi. APK'nın orijinal (döndürülmemiş) imzalama anahtarı önceki tüm platform sürümleri için kullanılır. Varsayılan olarak, Android 13 (API düzeyi 33) veya sonraki sürümleri çalıştıran cihazlarda desteklenen döndürülmüş imzalama anahtarları v3.1 imzalama bloğuyla kullanılır.

Not: Uygulamanız, Android 12L (API düzeyi 32) veya önceki sürümleri çalıştıran bir cihazda döndürülen imzalama anahtarıyla imzalandıysa uygulamanızı Android 9 (API düzeyi 28) için döndürülmüş imzalama anahtarıyla imzalamaya devam etmek üzere --rotation-min-sdk-version 28 kullanmanız gerekir.

--v1-signing-enabled <true | false>
apksigner ürününün, geleneksel, JAR tabanlı imzalama şemasını kullanarak belirtilen APK paketini imzalayıp imzalayacağını belirler. Araç, bu imza şemasının ne zaman uygulanacağına karar vermek için varsayılan olarak --min-sdk-version ve --max-sdk-version değerlerini kullanır.
--v2-signing-enabled <true | false>
apksigner tarafından belirtilen APK paketini APK İmza Şeması v2'yi kullanarak imzalayıp imzalamayacağını belirler. Varsayılan olarak, araç bu imza şemasının ne zaman uygulanacağına karar vermek için --min-sdk-version ve --max-sdk-version değerlerini kullanır.
--v3-signing-enabled <true | false>
apksigner tarafından belirtilen APK paketini APK İmza Şeması v3'ü kullanarak imzalayıp imzalamayacağını belirler. Varsayılan olarak, araç bu imza şemasının ne zaman uygulanacağına karar vermek için --min-sdk-version ve --max-sdk-version değerlerini kullanır.
--v4-signing-enabled <true | false | only>

apksigner ürününün, belirtilen APK paketini APK İmza Şeması v4'ü kullanarak imzalayıp imzalayacağını belirler. Bu şema ayrı bir dosyada (apk-name.apk.idsig) imza oluşturur. true ve APK imzalanmamışsa --min-sdk-version ve --max-sdk-version değerlerine göre v2 veya v3 imzası oluşturulur. Daha sonra komut, imzalı APK'nın içeriğine göre .idsig dosyasını oluşturur.

APK'yı ve çağrıdan önceki imzaları değiştirmeden yalnızca v4 imzasını oluşturmak için only kullanın. APK'nın halihazırda bir v2 veya v3 imzası yoksa ya da imza, geçerli çağrı için sağlanandan farklı bir anahtar kullanıyorsa only başarısız olur.

Varsayılan olarak, araç bu imza şemasının ne zaman uygulanacağına karar vermek için --min-sdk-version ve --max-sdk-version değerlerini kullanır.

-v, --verbose
Ayrıntılı çıkış modunu kullanın.

İmzalayan başına seçenekler

Aşağıdaki seçenekler, belirli bir imzalayanın yapılandırmasını belirtir. Uygulamanızı yalnızca tek bir imzalayanla imzaladıysanız bu seçenekler gerekli değildir.

--next-signer <signer-options>
Her imzalayan için farklı genel seçenekler belirtmek amacıyla kullanılır.
--v1-signer-name <basename>
Mevcut imzalayanın JAR tabanlı imzasını oluşturan dosyaların temel adı. Varsayılan olarak apksigner, bu imzalayan için KeyStore'un anahtar takma adını veya anahtar dosyasının temel adını kullanır.

Anahtar ve sertifika seçenekleri

Aşağıdaki seçenekler imzalayanın özel anahtarını ve sertifikasını belirtir:

--ks <filename>
İmzalayan kullanıcının özel anahtarı ve sertifika zinciri, belirtilen Java tabanlı KeyStore dosyasında bulunur. Dosya adı "NONE" olarak ayarlanırsa anahtarı ve sertifikayı içeren KeyStore için dosya belirtilmesi gerekmez. Bazı PKCS #11 KeyStore'lar için bu durum geçerlidir.
--ks-key-alias <alias>
KeyStore'da imzalayanın özel anahtarını ve sertifika verilerini temsil eden takma adın adı. İmzalayanla ilişkili KeyStore'da birden fazla anahtar varsa bu seçeneği belirtmeniz gerekir.
--ks-pass <input-format>

İmzalayanın özel anahtarını ve sertifikasını içeren KeyStore için şifre. KeyStore açmak için şifre belirtmelisiniz. apksigner aracı aşağıdaki biçimleri destekler:

  • pass:<password> – Şifre, apksigner sign komutunun geri kalanıyla birlikte satır içinde sağlanır.
  • env:<name>: Şifre, belirtilen ortam değişkeninde depolanır.
  • file:<filename> – Şifre, belirtilen dosyada tek bir satır olarak depolanır.
  • stdin – Şifre, standart giriş akışında tek bir satır olarak sağlanır. Bu, --ks-pass için varsayılan davranıştır.

Not: Aynı dosyaya birden fazla şifre eklerseniz bunları ayrı satırlarda belirtin. apksigner aracı, şifreleri imzalayanları belirtme sıranıza göre APK'yı imzalayanlarla ilişkilendirir. İmzalayan için iki şifre sağladıysanız apksigner ilk şifreyi KeyStore şifresi, ikincisini ise anahtar şifresi olarak yorumlar.

--pass-encoding <charset>
ASCII olmayan karakterler içeren şifreler işlenmeye çalışılırken ibm437 veya utf-8 gibi belirtilen karakter kodlamalarını içerir.

Keytool genellikle anahtar depolarını konsolun varsayılan karakter kümesini kullanarak şifreyi dönüştürerek şifreler. Varsayılan olarak, apksigner şifrenin çeşitli biçimlerini kullanarak şifre çözmeyi dener:

  • Unicode biçimi
  • JVM varsayılan karakter kümesi kullanılarak kodlanmış form
  • Java 8 ve daha eski sürümlerde konsolun varsayılan karakter kümesi kullanılarak kodlanmış form
  • Java 9'da apksigner, konsolun karakter kümesini algılayamıyor. ASCII olmayan bir şifre kullanıldığında --pass-encoding belirtmeniz gerekebilir. Bu seçeneği, keytool'un farklı bir işletim sisteminde veya farklı bir yerel ayarda oluşturduğu KeyStore'larda da belirtmeniz gerekebilir.

    --key-pass <input-format>

    İmzalayan kişinin özel anahtarının şifresi. Özel anahtar şifre korumalıysa bu şifre gereklidir. apksigner aracı aşağıdaki biçimleri destekler:

    • pass:<password> – Şifre, apksigner sign komutunun geri kalanıyla birlikte satır içinde sağlanır.
    • env:<name>: Şifre, belirtilen ortam değişkeninde depolanır.
    • file:<filename> – Şifre, belirtilen dosyada tek bir satır olarak depolanır.
    • stdin – Şifre, standart giriş akışında tek bir satır olarak sağlanır. Bu, --key-pass için varsayılan davranıştır.
    --ks-type <algorithm>
    İmzalayanın özel anahtarını ve sertifikasını içeren KeyStore ile ilişkili tür veya algoritma. Varsayılan olarak apksigner, Güvenlik özellikleri dosyasında keystore.type sabiti olarak tanımlanan türü kullanır.
    --ks-provider-name <name>
    İmzalayanın KeyStore uygulaması isteğinde bulunurken kullanılacak JCA Sağlayıcısı'nın adı. Varsayılan olarak apksigner en yüksek öncelikli sağlayıcıyı kullanır.
    --ks-provider-class <class-name>
    İmzalayanın KeyStore uygulaması isteğinde bulunurken kullanılacak JCA Sağlayıcısının tam nitelikli sınıf adı. Bu seçenek, --ks-provider-name için alternatif olarak işlev görür. Varsayılan olarak apksigner, --ks-provider-name seçeneğiyle belirtilen sağlayıcıyı kullanır.
    --ks-provider-arg <value>
    JCA Provider sınıfının oluşturucusu için bağımsız değişken olarak iletilecek dize değeri. Sınıfın kendisi --ks-provider-class seçeneğiyle tanımlanır. Varsayılan olarak apksigner, sınıfın sıfır bağımsız değişken oluşturucusunu kullanır.
    --key <filename>
    İmzalayanın özel anahtarını içeren dosyanın adı. Bu dosya, PKCS #8 DER biçimini kullanmalıdır. Anahtar şifre korumalıysa --key-pass seçeneğini kullanarak farklı bir giriş biçimi belirtmediğiniz sürece apksigner standart giriş kullanarak şifre ister.
    --cert <filename>
    İmzalayanın sertifika zincirini içeren dosyanın adı. Bu dosya, X.509 PEM veya DER biçimini kullanmalıdır.

    Komutu doğrula

    apksigner doğrulama komutunda aşağıdaki seçenekler bulunur.

    --print-certs
    APK'nın imzalama sertifikalarıyla ilgili bilgileri göster.
    --min-sdk-version <integer>
    APK'nın imzasının doğrulanacağını onaylamak için apksigner tarafından kullanılan en düşük Android Framework API düzeyi. Daha yüksek değerler, aracın uygulamayı imzalarken daha güçlü güvenlik parametreleri kullanmasına izin verir ancak APK'nın kullanılabilirliğini, Android'in daha yeni sürümlerini çalıştıran cihazlarla sınırlandırır. apksigner, varsayılan olarak uygulamanın manifest dosyasındaki minSdkVersion özelliğinin değerini kullanır.
    --max-sdk-version <integer>
    APK'nın imzasının doğrulanacağını onaylamak için apksigner tarafından kullanılan en yüksek Android Framework API düzeyi. Varsayılan olarak araç mümkün olan en yüksek API düzeyini kullanır.
    -v, --verbose
    Ayrıntılı çıkış modunu kullanın.
    -Werr
    Uyarıları hata olarak ele alın.

    Örnekler

    Aşağıda, apksigner özelliğinin kullanıldığı örnekler verilmiştir.

    Bir APK imzalayın

    KeyStore'daki tek anahtar olan release.jks öğesini kullanarak bir APK'yı imzalayın:

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

    Ayrı dosyalar olarak depolanan bir özel anahtar ve sertifikayı kullanarak APK'yı imzalayın:

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

    İki anahtar kullanarak APK imzalama:

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

    Bir APK'yı, döndürülmüş imzalama anahtarı ve rotasyon hedefleme SDK'sı 28 ve sonraki bir sürümüyle imzalayın:

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

    Bir APK'yı döndürülmüş imzalama anahtarı ve rotasyon hedefleme SDK'sı 33 ve sonraki sürümleri ile imzalayın:

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

    APK'nın imzasını doğrulama

    APK'nın imzalarının, desteklediği tüm Android platformlarında geçerli olarak onaylanmasının beklendiğini kontrol edin:

    $ apksigner verify app.apk
    

    APK'nın imzalarının Android 4.0.3 (API düzeyi 15) ve sonraki sürümlerde geçerli olarak onaylanmasının beklendiğini kontrol edin:

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

    İmzalama anahtarlarını değiştirme

    Anahtar rotasyonunu destekleyen bir imzalama sertifikası sınıfını etkinleştirin:

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

    İmzalama anahtarlarınızı tekrar döndürün:

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