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ıza ve bir APK'nın imzasının o APK tarafından desteklenen tüm Android platform sürümlerinde başarılı bir şekilde doğrulanacağını onaylamanıza olanak tanır.

Bu sayfada, aracı kullanmayla ilgili kısa bir kılavuz sunulmakta ve aracın desteklediği farklı komut satırı seçenekleri için referans olarak kullanılmaktadır. apksigner aracının APK'larınızı imzalamak için nasıl kullanıldığıyla ilgili daha ayrıntılı bir açıklama için Uygulamanızı imzalama başlıklı makaleyi inceleyin.

Dikkat: APK'nızı apksigner kullanarak imzalarsanız 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 aracını kullanıyorsanız APK'yı imzalamadan önce kullanın.

Kullanım

APK imzalama

apksigner aracını kullanarak APK imzalama 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ının PKCS #8 biçimini, sertifika dosyasının ise X.509 biçimini kullanması gerekir.

Genellikle bir APK'yı yalnızca bir imzalayan kullanarak imzalarsınız. Bir APK'yı birden fazla imzalayan kullanarak imzalamanız gerekiyorsa her 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

Bir APK'nın imzasının desteklenen platformlarda başarılı bir şekilde doğrulandığını onaylamak için aşağıdaki söz dizimini kullanabilirsiniz:

apksigner verify [options] app-name.apk

İmzalama anahtarlarını döndürme

İmzalama sertifikası soyunu veya yeni bir imza dizisini döndürme 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 listelerde, apksigner aracının desteklediği her komut için seçenekler grubu yer almaktadır.

İmzalama komutu

apksigner işaret komutunun aşağıdaki seçenekleri vardır.

Genel seçenekler

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

--out <apk-filename>

İmzalı APK'yı kaydetmek istediğiniz konum. Bu seçenek açıkça belirtilmemişse APK paketi yerinde imzalanır ve giriş APK dosyası üzerine yazılır.

--min-sdk-version <integer>

apksigner'nin, APK'nın imzasının doğrulanacağını onaylamak için kullandığı en düşük Android framework API düzeyi. Daha yüksek değerler, uygulamanın imzalanması sırasında aracın daha güçlü güvenlik parametreleri kullanmasına olanak tanır ancak APK'nın kullanılabilirliğini Android'in daha yeni sürümlerini çalıştıran cihazlarla sınırlar. apksigner, varsayılan olarak uygulamanın manifest dosyasındaki minSdkVersion özelliğinin değerini kullanır.

--max-sdk-version <integer>

apksigner hizmetinin, APK'nın imzasının doğrulanacağını onaylamak için kullandığı en yüksek Android framework API düzeyi. Araç, varsayılan olarak 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ümlerin yüklü olduğu bir cihazda döndürülmüş bir imzalama anahtarıyla imzalandıysa Android 9 (API düzeyi 28) için döndürülmüş imzalama anahtarıyla uygulamanızı imzalamaya devam etmek üzere --rotation-min-sdk-version 28 kullanmanız gerekir.

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

apksigner öğesinin, geleneksel JAR tabanlı imza şemasını kullanarak belirtilen APK paketini imzalayıp imzalamayacağı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'nin, APK İmza Şeması v2'yi kullanarak belirtilen APK paketini imzalayıp imzalamayacağını belirler. Araç, varsayılan olarak 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'nin, APK İmza Şeması v3'ü kullanarak belirtilen APK paketini imzalayıp imzalamayacağını belirler. Araç, varsayılan olarak 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, APK İmza Şeması v4'ü kullanarak belirtilen APK paketini imzalayıp imzalamayacağı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. Ardından komut, imzalı APK'nın içeriğine göre .idsig dosyasını oluşturur.

APK'yı ve çağırmadan önce sahip olduğu imzaları değiştirmeden yalnızca v4 imzasını oluşturmak için only'ı kullanın. APK'da v2 veya v3 imzası yoksa ya da kullanılan imza, mevcut çağırma işlemi için sağlanan anahtardan farklı bir anahtar kullanıyorsa only başarısız olur.

Araç, varsayılan olarak 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 bir imzalayan kullanarak imzalarsanız bu seçenekler gerekli değildir.

--next-signer <signer-options>

Her imzalayan için farklı genel seçenekleri belirtmek üzere kullanılır.

--v1-signer-name <basename>

Geçerli 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ın özel anahtarı ve sertifika zinciri, belirtilen Java tabanlı KeyStore dosyasında bulunur. Dosya adı "NONE" olarak ayarlanmışsa anahtar ve sertifika içeren KeyStore'un dosya belirtmesine gerek yoktur. Bu durum, bazı PKCS #11 KeyStore'lar için 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 birden fazla anahtar içeriyorsa bu seçeneği belirtmeniz gerekir.

--ks-pass <input-format>

İmzalayanın özel anahtarını ve sertifikasını içeren anahtar deposunun şifresi. Bir KeyStore'u açmak için şifre sağlamanız gerekir. apksigner aracı aşağıdaki biçimleri destekler:

• pass:<password> – Şifre, apksigner sign komutunun geri kalanıyla birlikte satır içi olarak sağlanır.
• env:<name>: Şifre, belirtilen ortam değişkeninde depolanır.
• file:<filename> – Şifre, belirtilen dosyada tek bir satır olarak saklanı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ı belirttiğiniz sıraya göre bir APK'nın imzalayanlarıyla ilişkilendirir. İmzalayan için iki şifre sağladıysanız apksigner, ilk şifreyi KeyStore şifresi, ikinci şifreyi ise anahtar şifresi olarak yorumlar.

--pass-encoding <charset>

ASCII olmayan karakterler içeren şifreleri işlemeye çalışırken ibm437 veya utf-8 gibi belirtilen karakter kodlamalarını içerir.

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

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 kodlanan form

Java 9'da apksigner, konsolun karakter kümesini algılayamaz. ASCII dışı 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'lar için de belirtmeniz gerekebilir.

--key-pass <input-format>

Özel anahtar şifreyle korunuyorsa imzalayanın özel anahtarının şifresi gerekir. apksigner aracı aşağıdaki biçimleri destekler:

• pass:<password>: Şifre, apksigner sign komutunun geri kalanıyla birlikte satır içi olarak sağlanır.
• env:<name>: Şifre, belirtilen ortam değişkeninde depolanır.
• file:<filename> – Şifre, belirtilen dosyada tek bir satır olarak saklanı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 anahtar deposuyla ilişkili tür veya algoritma. apksigner, varsayılan olarak Güvenlik özellikleri dosyasında keystore.type sabiti olarak tanımlanan türü kullanır.

--ks-provider-name <name>

İmzalayanın KeyStore uygulamasını isterken 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ını isterken kullanılacak JCA sağlayıcısının tam tanımlanmış sınıf adı. Bu seçenek, --ks-provider-name için alternatif olarak sunulur. 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şturucusunun bağımsız değişkeni olarak iletilecek bir 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şkenli 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 şifreyle korunuyorsa apksigner seçeneğini kullanarak farklı bir giriş biçimi belirtmediğiniz sürece, apksigner standart girişle şifreyi ister.--key-pass

--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ğrulama

apksigner doğrulama komutunun aşağıdaki seçenekleri vardır.

--print-certs

APK'nın imzalama sertifikalarıyla ilgili bilgileri gösterir.

--print-certs-pem

APK'nın imzalama sertifikalarıyla ilgili bilgileri gösterin ve her imzalama sertifikasının PEM kodlamasını stdout'a yazdırın.

--min-sdk-version <integer>

apksigner'nin, APK'nın imzasının doğrulanacağını onaylamak için kullandığı en düşük Android framework API düzeyi. Daha yüksek değerler, uygulamanın imzalanması sırasında aracın daha güçlü güvenlik parametreleri kullanmasına olanak tanır ancak APK'nın kullanılabilirliğini Android'in daha yeni sürümlerini çalıştıran cihazlarla sınırlar. apksigner, varsayılan olarak uygulamanın manifest dosyasındaki minSdkVersion özelliğinin değerini kullanır.

--max-sdk-version <integer>

apksigner hizmetinin, APK'nın imzasının doğrulanacağını onaylamak için kullandığı en yüksek Android framework API düzeyi. Araç, varsayılan olarak 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 değerlendirin.

Örnekler

Aşağıda apksigner kullanılan örnekler verilmiştir.

APK imzalama

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

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

Ayrı dosyalar olarak depolanan bir özel anahtar ve sertifika kullanarak APK imzalama:

$ 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

Rotasyona tabi tutulmuş bir imzalama anahtarıyla ve rotasyonun hedeflediği SDK sürümü 28 veya sonraki sürümlerle bir APK'yı imzalama:

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

Rotasyona tabi tutulmuş bir imzalama anahtarıyla ve rotasyonun SDK sürümü 33 veya sonraki sürümleri hedeflediği bir APK'yı imzalama:

$ 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, APK'nın desteklediği tüm Android platformlarında geçerli olarak onaylanması beklenip beklenmediğ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 onaylanıp onaylanmayacağını kontrol edin:

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

İmzalama anahtarlarını döndürme

Anahtar rotasyonunu destekleyen bir imzalama sertifikası soyunu etkinleştirin:

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

İmzalama anahtarlarınızı tekrar değiştirin:

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