apksigner

Alat apksigner, yang tersedia dalam Android SDK Build Tools revisi 24.0.3 dan yang lebih tinggi, memungkinkan Anda menandatangani APK dan mengonfirmasi bahwa tanda tangan APK akan berhasil diverifikasi di semua versi platform Android yang didukung oleh APK tersebut.

Halaman ini menyajikan panduan singkat dalam menggunakan alat dan berfungsi sebagai referensi bagi beragam opsi command line yang didukung oleh alat tersebut. Untuk mengetahui deskripsi lebih lengkap tentang cara alat apksigner digunakan untuk menandatangani APK, lihat Menandatangani aplikasi.

Perhatian: Jika Anda menandatangani APK menggunakan apksigner dan membuat perubahan lebih lanjut pada APK, tanda tangan APK menjadi tidak valid. Jika Anda menggunakan zipalign untuk menyesuaikan APK, gunakan sebelum menandatangani APK.

Penggunaan

Menandatangani APK

Sintaksis untuk penandatanganan APK menggunakan alat apksigner adalah sebagai berikut: 

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

Saat menandatangani APK menggunakan alat apksigner, Anda harus memberikan kunci pribadi dan sertifikat penanda tangan. Anda dapat memasukkan informasi ini dengan dua cara:

  • Menentukan file KeyStore menggunakan opsi --ks.
  • Menentukan file kunci pribadi dan file sertifikat secara terpisah menggunakan opsi --key dan --cert. File kunci pribadi harus menggunakan format PKCS #8, dan file sertifikat harus menggunakan format X.509.

Biasanya, Anda dapat menandatangani APK cukup menggunakan satu penanda tangan. Jika Anda perlu menandatangani APK menggunakan beberapa penanda tangan, gunakan opsi --next-signer untuk memisahkan rangkaian opsi umum yang akan diterapkan ke setiap penanda tangan: 

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

Memverifikasi tanda tangan APK

Sintaksis untuk mengonfirmasi verifikasi tanda tangan APK yang berhasil di platform yang didukung adalah sebagai berikut: 

apksigner verify [options] app-name.apk

Merotasi kunci tanda tangan

Sintaksis untuk merotasi urutan sertifikat penandatanganan, atau urutan baru tanda tangan, adalah sebagai berikut:

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

Opsi

Daftar berikut mencakup sekumpulan opsi untuk setiap perintah yang didukung oleh alat apksigner.

Perintah tanda tangan

Perintah tanda tangan apksigner memiliki opsi berikut.

Opsi umum

Opsi berikut menentukan setelan dasar untuk diterapkan ke penanda tangan:

--out <apk-filename>
Lokasi tempat Anda ingin menyimpan APK yang ditandatangani. Jika opsi ini tidak disediakan secara eksplisit, paket APK akan ditandatangani di tempat, yang menimpa file APK input.
--min-sdk-version <integer>
API level framework Android terendah yang digunakan apksigner untuk mengonfirmasi bahwa tanda tangan APK akan diverifikasi. Nilai yang lebih tinggi memungkinkan alat menggunakan parameter keamanan yang lebih kuat saat menandatangani aplikasi tetapi membatasi ketersediaan APK ke perangkat yang menjalankan versi Android yang lebih baru. Secara default, apksigner menggunakan nilai atribut minSdkVersion dari file manifes aplikasi.
--max-sdk-version <integer>
API level framework Android tertinggi yang digunakan apksigner untuk mengonfirmasi bahwa tanda tangan APK akan diverifikasi. Secara default, alat ini menggunakan API level setinggi mungkin.
--rotation-min-sdk-version <integer>
API level terendah yang harus digunakan oleh kunci penandatanganan yang dirotasi oleh APK untuk menghasilkan tanda tangan APK. Kunci penandatanganan asli (tidak dirotasi) untuk APK akan digunakan untuk semua versi platform sebelumnya. Secara default, kunci penandatanganan yang dirotasi, yang didukung di perangkat yang menjalankan Android 13 (API level 33) atau yang lebih tinggi, digunakan dengan blok penandatanganan v3.1.

Catatan: Jika aplikasi Anda telah ditandatangani dengan kunci penandatanganan yang dirotasi pada perangkat yang menjalankan Android 12L (API level 32) atau yang lebih rendah, Anda harus menggunakan --rotation-min-sdk-version 28 untuk melanjutkan penandatanganan aplikasi dengan kunci penandatanganan yang dirotasi untuk Android 9 (API level 28).

--v1-signing-enabled <true | false>
Menentukan apakah apksigner menandatangani paket APK tertentu menggunakan skema penandatanganan tradisional berbasis JAR. Secara default, alat tersebut akan menggunakan nilai --min-sdk-version dan --max-sdk-version untuk menentukan kapan harus menerapkan skema tanda tangan ini.
--v2-signing-enabled <true | false>
Menentukan apakah apksigner menandatangani paket APK tertentu menggunakan APK Signature Scheme v2. Secara default, alat tersebut akan menggunakan nilai --min-sdk-version dan --max-sdk-version untuk menentukan kapan harus menerapkan skema tanda tangan ini.
--v3-signing-enabled <true | false>
Menentukan apakah apksigner menandatangani paket APK tertentu menggunakan APK Signature Scheme v3. Secara default, alat tersebut akan menggunakan nilai --min-sdk-version dan --max-sdk-version untuk menentukan kapan harus menerapkan skema tanda tangan ini.
--v4-signing-enabled <true | false | only>

Menentukan apakah apksigner menandatangani paket APK tertentu menggunakan APK Signature Scheme v4. Skema ini menghasilkan tanda tangan dalam file terpisah (apk-name.apk.idsig). Jika true dan APK tidak ditandatangani, tanda tangan v2 atau v3 akan dihasilkan berdasarkan nilai --min-sdk-version dan --max-sdk-version. Perintah tersebut kemudian menghasilkan file .idsig berdasarkan konten APK yang ditandatangani.

Gunakan only untuk menghasilkan tanda tangan v4 saja tanpa memodifikasi APK dan tanda tangan yang dimilikinya sebelum pemanggilan. only akan gagal jika APK tidak memiliki tanda tangan v2 atau v3, atau jika tanda tangan menggunakan kunci yang berbeda dari yang disediakan untuk pemanggilan saat ini.

Secara default, alat tersebut akan menggunakan nilai --min-sdk-version dan --max-sdk-version untuk menentukan kapan harus menerapkan skema tanda tangan ini.

-v, --verbose
Menggunakan mode output panjang.

Opsi per penanda tangan

Opsi berikut ini akan menentukan konfigurasi penanda tangan tertentu. Opsi ini tidak diperlukan jika Anda menandatangani aplikasi hanya menggunakan satu penanda tangan.

--next-signer <signer-options>
Digunakan untuk menentukan opsi umum yang berbeda bagi setiap penanda tangan.
--v1-signer-name <basename>
Nama dasar file yang berisi tanda tangan berbasis JAR untuk penanda tangan saat ini. Secara default, apksigner menggunakan alias kunci dari KeyStore atau nama dasar file kunci untuk penanda tangan ini.

Opsi kunci dan sertifikat

Opsi berikut menentukan kunci pribadi dan sertifikat penanda tangan:

--ks <filename>
Kunci pribadi dan rangkaian sertifikat penanda tangan berada di file KeyStore berbasis Java yang ditentukan. Jika nama file ditetapkan ke "NONE", KeyStore yang berisi kunci dan sertifikat tidak akan memerlukan file yang ditentukan, yang merupakan kasus bagi beberapa KeyStore PKCS #11.
--ks-key-alias <alias>
Nama alias yang merepresentasikan kunci pribadi dan data sertifikat penanda tangan dalam KeyStore. Jika KeyStore yang dikaitkan dengan penanda tangan berisi beberapa kunci, Anda harus menentukan opsi ini.
--ks-pass <input-format>

Sandi untuk KeyStore yang berisi kunci pribadi dan sertifikat penanda tangan. Anda harus menyediakan sandi untuk membuka KeyStore. Alat apksigner mendukung format berikut:

  • pass:<password> – Sandi yang disediakan sesuai dengan perintah apksigner sign lainnya.
  • env:<name> – Sandi disimpan dalam variabel lingkungan tertentu.
  • file:<filename> – Sandi disimpan sebagai satu baris dalam file tertentu.
  • stdin – Sandi disediakan sebagai satu baris dalam stream input standar. Ini adalah perilaku default untuk --ks-pass.

Catatan: Jika Anda memasukkan beberapa sandi dalam file yang sama, tentukan sandi tersebut di baris yang berbeda. Alat apksigner akan mengaitkan sandi dengan penanda tangan APK berdasarkan urutan yang Anda tentukan kepada penanda tangan. Jika Anda telah memberikan dua sandi untuk penanda tangan, apksigner akan menginterpretasikan sandi pertama sebagai sandi KeyStore dan yang kedua sebagai sandi kunci.

--pass-encoding <charset>
Menyertakan encoding karakter yang ditentukan, seperti ibm437 atau utf-8, ketika mencoba menangani sandi yang berisi karakter non-ASCII.

Keytool sering mengenkripsi keystore dengan mengonversi sandi menggunakan charset default konsol. Secara default, apksigner mencoba mendekripsi menggunakan beberapa bentuk sandi:

  • Bentuk Unicode
  • Bentuk yang dienkode menggunakan charset default JVM
  • Pada Java 8 dan yang lebih lama, bentuk yang dienkode menggunakan charset default konsol

    • Pada Java 9, apksigner tidak dapat mendeteksi charset konsol. Anda mungkin perlu menentukan --pass-encoding ketika yang digunakan adalah sandi non-ASCII. Anda mungkin juga perlu menentukan opsi ini dengan KeyStore yang dibuat oleh keytool pada OS yang berbeda atau di tempat yang berbeda.

    --key-pass <input-format>

    Sandi untuk kunci pribadi penanda tangan, yang diperlukan jika kunci pribadi dilindungi sandi. Alat apksigner mendukung format berikut:

    • pass:<password> – Sandi disediakan sesuai dengan perintah apksigner sign lainnya.
    • env:<name> – Sandi disimpan dalam variabel lingkungan tertentu.
    • file:<filename> – Sandi disimpan sebagai satu baris dalam file tertentu.
    • stdin – Sandi disediakan sebagai satu baris dalam stream input standar. Ini adalah perilaku default untuk --key-pass.
    --ks-type <algorithm>
    Jenis atau algoritme yang dikaitkan dengan KeyStore yang berisi kunci pribadi dan sertifikat penanda tangan. Secara default, apksigner menggunakan jenis yang ditentukan sebagai konstanta keystore.type dalam file properti Keamanan.
    --ks-provider-name <name>
    Nama Penyedia JCA yang digunakan saat meminta implementasi KeyStore penanda tangan. Secara default, apksigner menggunakan penyedia dengan prioritas tertinggi.
    --ks-provider-class <class-name>
    Nama class Penyedia JCA yang sepenuhnya memenuhi syarat yang digunakan saat meminta implementasi KeyStore penanda tangan. Opsi ini berfungsi sebagai alternatif untuk --ks-provider-name. Secara default, apksigner menggunakan penyedia yang ditentukan dengan opsi --ks-provider-name.
    --ks-provider-arg <value>
    Nilai string yang akan diberikan sebagai argumen bagi konstruktor class Penyedia JCA; class itu sendiri didefinisikan dengan opsi --ks-provider-class. Secara default, apksigner menggunakan konstruktor nol argumen class.
    --key <filename>
    Nama file yang berisi kunci pribadi penanda tangan. File ini harus menggunakan format DER PKCS #8. Jika kuncinya dilindungi sandi, apksigner akan meminta sandi menggunakan input standar kecuali jika Anda menentukan jenis format input lain yang menggunakan opsi --key-pass.
    --cert <filename>
    Nama file yang berisi rantai sertifikat penanda tangan. File ini harus menggunakan format PEM atau DER X.509.

    Perintah verifikasi

    Perintah verifikasi apksigner memiliki opsi berikut.

    --print-certs
    Menampilkan informasi tentang sertifikat penandatanganan APK.
    --min-sdk-version <integer>
    API level framework Android terendah yang digunakan apksigner untuk mengonfirmasi bahwa tanda tangan APK akan diverifikasi. Nilai yang lebih tinggi memungkinkan alat menggunakan parameter keamanan yang lebih kuat saat menandatangani aplikasi tetapi membatasi ketersediaan APK ke perangkat yang menjalankan versi Android yang lebih baru. Secara default, apksigner menggunakan nilai atribut minSdkVersion dari file manifes aplikasi.
    --max-sdk-version <integer>
    API level framework Android tertinggi yang digunakan apksigner untuk mengonfirmasi bahwa tanda tangan APK akan diverifikasi. Secara default, alat ini menggunakan API level setinggi mungkin.
    -v, --verbose
    Menggunakan mode output panjang.
    -Werr
    Memperlakukan peringatan sebagai error.

    Contoh

    Berikut adalah contoh yang menggunakan apksigner.

    Menandatangani APK

    Menandatangani APK menggunakan release.jks, yang merupakan satu-satunya kunci di KeyStore: 

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

    Menandatangani APK menggunakan kunci pribadi dan sertifikat yang disimpan sebagai file terpisah: 

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

    Menandatangani APK menggunakan dua kunci: 

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

    Menandatangani APK dengan kunci penandatanganan yang dirotasi dan SDK penargetan rotasi versi 28+: 

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

    Menandatangani APK dengan kunci penandatanganan yang dirotasi dan SDK penargetan rotasi versi 33+: 

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

    Memverifikasi tanda tangan APK

    Periksa apakah tanda tangan APK diharapkan untuk dikonfirmasi sebagai valid pada semua platform Android yang didukung APK: 

    $ apksigner verify app.apk

    Periksa apakah tanda tangan APK diharapkan untuk dikonfirmasi sebagai valid pada Android 4.0.3 (API level 15) dan yang lebih tinggi: 

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

    Merotasi kunci tanda tangan

    Aktifkan urutan sertifikat penandatanganan yang mendukung pemutaran kunci:

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

    Memutar kembali tombol penandatanganan:

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