apksigner

เครื่องมือ apksigner ซึ่งมีอยู่ในเวอร์ชัน 24.0.3 ขึ้นไป เครื่องมือสร้าง APK ของ Android SDK จะช่วยให้คุณสามารถ รับรอง APK และยืนยันว่า ลายเซ็นของ APK จะได้รับการยืนยันใน Android ทุกเวอร์ชันสำเร็จ แพลตฟอร์มที่ APK นั้นรองรับ

หน้านี้จะแนะนำสั้นๆ ในการใช้ เครื่องมือและทำหน้าที่เป็นข้อมูลอ้างอิงสำหรับตัวเลือกบรรทัดคำสั่งต่างๆ ที่เครื่องมือนี้สนับสนุน หากต้องการคำอธิบายที่สมบูรณ์ยิ่งขึ้นเกี่ยวกับวิธี เครื่องมือ apksigner ใช้สำหรับรับรอง APK ของคุณ โปรดดูส่วนรับรองแอป

ข้อควรระวัง: หากคุณรับรอง APK โดยใช้ apksigner และทำการเปลี่ยนแปลง APK เพิ่มเติมจะทำให้ลายเซ็นของ APK ไม่ถูกต้อง หากคุณใช้ zipalign เพื่อจัดข้อความ APK ของคุณ ให้ใช้ไฟล์ ก่อนลงนาม APK

การใช้งาน

ลงนาม APK

ไวยากรณ์สำหรับการรับรอง APK โดยใช้เครื่องมือ apksigner เป็นไปตาม ดังต่อไปนี้: 

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

เมื่อคุณลงนาม APK โดยใช้เครื่องมือ apksigner คุณต้องระบุ คีย์ส่วนตัวและใบรับรองของผู้ลงนาม คุณสามารถรวมข้อมูลนี้ใน มี 2 วิธี ได้แก่

  • ระบุไฟล์ KeyStore โดยใช้ตัวเลือก --ks
  • ระบุไฟล์คีย์ส่วนตัวและไฟล์ใบรับรองแยกต่างหากโดยใช้ --key และ --cert ตัวเลือกตามลำดับ ไฟล์คีย์ส่วนตัวต้องใช้รูปแบบ PKCS #8 และไฟล์ใบรับรองต้อง ใช้รูปแบบ X.509

โดยปกติ คุณจะลงนาม APK โดยใช้ผู้ลงนามเพียงรายเดียว หากคุณจำเป็นต้องทำดังนี้ ลงนาม APK โดยใช้ผู้ลงนามหลายคน ใช้ตัวเลือก --next-signer เพื่อแยกชุดตัวเลือกทั่วไปเป็น ให้ใช้กับผู้ลงนามแต่ละคน 

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

ยืนยันลายเซ็นของ APK

ไวยากรณ์สำหรับยืนยันว่าการยืนยันลายเซ็นของ APK สำเร็จ บนแพลตฟอร์มที่รองรับดังต่อไปนี้ 

apksigner verify [options] app-name.apk

หมุนเวียนคีย์การรับรอง

ชุดคำสั่งตามรูปแบบไวยากรณ์สำหรับการหมุนเวียนบรรทัดฐานใบรับรองที่ลงนามหรือลำดับใหม่ของ ดังนี้

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

ตัวเลือก

รายการต่อไปนี้มีชุดตัวเลือกสำหรับแต่ละคำสั่งที่ฟังก์ชัน รองรับเครื่องมือ apksigner

ลงนามในคำสั่ง

คำสั่งเครื่องหมาย apksigner มีตัวเลือกต่อไปนี้

ตัวเลือกทั่วไป

ตัวเลือกต่อไปนี้ระบุการตั้งค่าพื้นฐานที่จะใช้กับผู้เซ็น

--out <apk-filename>
ตำแหน่งที่คุณต้องการบันทึก APK ที่ลงชื่อแล้ว หากตัวเลือกนี้ไม่ได้ ที่ระบุอย่างชัดเจน แพ็กเกจ APK มีการลงชื่อกำกับ ซึ่งจะเขียนทับ ไฟล์ APK ที่ป้อน
--min-sdk-version <integer>
ระดับ API เฟรมเวิร์ก Android ต่ำสุดที่ apksigner ใช้เพื่อ ให้ยืนยันว่าลายเซ็นของ APK จะได้รับการยืนยัน ค่าที่สูงขึ้นช่วยให้ เครื่องมือที่จะใช้พารามิเตอร์ความปลอดภัยที่เข้มงวดขึ้นเมื่อรับรองแอป แต่จำกัด ความพร้อมให้บริการของ APK สำหรับอุปกรณ์ที่ใช้ Android เวอร์ชันล่าสุด โดยค่าเริ่มต้น apksigner จะใช้ค่าของพารามิเตอร์ minSdkVersion จากไฟล์ Manifest ของแอป
--max-sdk-version <integer>
ระดับ API เฟรมเวิร์ก Android สูงสุดที่ apksigner ใช้ เพื่อยืนยันว่าลายเซ็นของ APK จะได้รับการยืนยัน โดยค่าเริ่มต้น เครื่องมือ ใช้ระดับ API สูงสุดเท่าที่จะเป็นไปได้
--rotation-min-sdk-version <integer>
ระดับ API ต่ำสุดที่หมุนเวียนการรับรองของ APK ควรใช้เพื่อสร้างลายเซ็นของ APK จะมีการใช้คีย์ Signing ดั้งเดิม (ไม่หมุน) สำหรับ APK ทั้งหมด เวอร์ชันก่อนๆ ของแพลตฟอร์ม โดยค่าเริ่มต้น คีย์การรับรองแบบหมุนเวียน ซึ่งรองรับในอุปกรณ์ที่ใช้ Android 13 (API ระดับ 33) ขึ้นไปจะใช้กับบล็อกการรับรองเวอร์ชัน 3.1

หมายเหตุ: หากแอปลงนามด้วยการรับรองแบบหมุนเวียน ในอุปกรณ์ที่ใช้ Android 12L (API ระดับ 32) หรือต่ำกว่า คุณก็จะ ต้องใช้ --rotation-min-sdk-version 28 เพื่อลงนามต่อ แอปด้วยคีย์ Signing แบบหมุนเวียนสำหรับ Android 9 (API ระดับ 28)

--v1-signing-enabled <true | false>
ระบุว่า apksigner ลงนามในแพ็กเกจ APK ที่กำหนดหรือไม่ โดยใช้แผนการลงนามแบบดั้งเดิมที่ใช้ JAR โดยค่าเริ่มต้น เครื่องมือจะใช้ ค่าของ --min-sdk-version และ --max-sdk-version เพื่อตัดสินใจว่าจะใช้ลายเซ็นนี้เมื่อใด สคีม
--v2-signing-enabled <true | false>
ระบุว่า apksigner ลงนามในแพ็กเกจ APK ที่กำหนดหรือไม่ โดยใช้ APK Signature Scheme v2 โดยค่าเริ่มต้น เครื่องมือจะใช้ค่าของ --min-sdk-versionและ--max-sdk-versionจะตัดสินใจ เวลาที่ควรใช้รูปแบบลายเซ็นนี้
--v3-signing-enabled <true | false>
ระบุว่า apksigner ลงนามในแพ็กเกจ APK ที่กำหนดหรือไม่ โดยใช้ APK Signature Scheme v3 โดยค่าเริ่มต้น เครื่องมือจะใช้ค่าของ --min-sdk-versionและ--max-sdk-versionจะตัดสินใจ เวลาที่ควรใช้รูปแบบลายเซ็นนี้
--v4-signing-enabled <true | false | only>

ระบุว่า apksigner รับรองแพ็กเกจ APK ที่ระบุหรือไม่ โดยใช้ APK Signature Scheme v4 รูปแบบนี้ จะสร้างลายเซ็นในไฟล์แยกต่างหาก (apk-name.apk.idsig) หาก true และ APK ไม่ได้ลงนาม จะใช้ลายเซ็น v2 หรือ v3 สร้างขึ้นตามค่าของ --min-sdk-version และ --max-sdk-version จากนั้นคำสั่งจะสร้าง .idsig ไฟล์ตามเนื้อหาของ APK ที่ลงนาม

ใช้ only เพื่อสร้างเฉพาะ v4 ลายเซ็นโดยไม่แก้ไข APK และลายเซ็นใดๆ ที่มีก่อนการเรียกใช้ only ล้มเหลวหาก APK ไม่ มีลายเซ็น v2 หรือ v3 อยู่แล้ว หรือหากลายเซ็นใช้คีย์อื่น มากกว่าที่กำหนดไว้สำหรับการเรียกใช้ปัจจุบัน

โดยค่าเริ่มต้น เครื่องมือจะใช้ค่าของ --min-sdk-versionและ--max-sdk-versionจะตัดสินใจ เวลาที่ควรใช้รูปแบบลายเซ็นนี้

-v, --verbose
ใช้โหมดเอาต์พุตแบบละเอียด

ตัวเลือกต่อผู้ลงนาม

ตัวเลือกต่อไปนี้จะระบุการกำหนดค่าของผู้ลงนามแต่ละคน เหล่านี้ ตัวเลือกไม่จำเป็นหากคุณรับรองแอปโดยใช้ผู้ลงนามเพียง 1 รายเท่านั้น

--next-signer <signer-options>
ใช้เพื่อระบุตัวเลือกทั่วไปต่างๆ สำหรับผู้ลงนามแต่ละคน
--v1-signer-name <basename>
ชื่อฐานสำหรับไฟล์ที่ประกอบด้วยลายเซ็นแบบ JAR สำหรับ ผู้ลงนามปัจจุบัน โดยค่าเริ่มต้น apksigner จะใช้ชื่อแทนคีย์ของ KeyStore หรือชื่อพื้นฐานของไฟล์คีย์สำหรับผู้เซ็น

ตัวเลือกคีย์และใบรับรอง

ตัวเลือกต่อไปนี้ระบุคีย์ส่วนตัวและใบรับรองของผู้ลงนาม

--ks <filename>
คีย์ส่วนตัวและชุดใบรับรองของผู้ลงนามอยู่ใน ไฟล์ KeyStore แบบ Java หากตั้งชื่อไฟล์เป็น "NONE" KeyStore ที่มีคีย์และใบรับรองไม่จำเป็นต้องใช้ไฟล์ ซึ่งเป็นกรณีสำหรับ KeyStore ของ PKCS #11 บางรายการ
--ks-key-alias <alias>
ชื่อของชื่อแทนที่แสดงถึงคีย์ส่วนตัวของผู้ลงนามและ ข้อมูลใบรับรองภายใน KeyStore หากคีย์สโตร์เชื่อมโยงกับ เครื่องมือลงนามมีคีย์หลายรายการ คุณต้องระบุตัวเลือกนี้
--ks-pass <input-format>

รหัสผ่านสำหรับ KeyStore ที่มีคีย์ส่วนตัวของผู้ลงนามและ ใบรับรอง คุณต้องระบุรหัสผ่านเพื่อเปิด KeyStore เครื่องมือ apksigner รองรับรูปแบบต่อไปนี้

  • pass:<password> – ป้อนรหัสผ่านในบรรทัด ด้วยคำสั่ง apksigner sign ที่เหลือ
  • env:<name> – รหัสผ่านจัดเก็บอยู่ใน ตัวแปรสภาพแวดล้อม
  • file:<filename> – รหัสผ่านจะจัดเก็บเป็น บรรทัดเดียวในไฟล์ที่กำหนด
  • stdin – รหัสผ่านจะแสดงเป็นบรรทัดเดียวใน สตรีมอินพุตมาตรฐาน นี่คือลักษณะการทำงานเริ่มต้นของ --ks-pass

หมายเหตุ: หากคุณใส่รหัสผ่านหลายรหัสเป็นรหัสเดียวกัน ให้ระบุไฟล์โดยแยกบรรทัดกัน เครื่องมือ apksigner เชื่อมโยงรหัสผ่านกับผู้ลงนาม APK ตามลำดับ ที่คุณจะระบุผู้ลงนาม หากคุณระบุรหัสผ่านไว้ 2 รหัสสำหรับผู้ลงนาม apksigner ตีความรหัสผ่านแรกเป็น KeyStore และรหัสผ่านที่ 2 เป็นรหัสผ่านหลัก

--pass-encoding <charset>
รวมการเข้ารหัสอักขระที่ระบุ เช่น ibm437 หรือ utf-8 เมื่อพยายาม จัดการรหัสผ่านที่มีอักขระที่ไม่ใช่ ASCII

เครื่องมือคีย์มักจะเข้ารหัสคีย์สโตร์ด้วยการเปลี่ยนรหัสผ่านโดยใช้ค่าเริ่มต้นของคอนโซล ชุดอักขระ โดยค่าเริ่มต้น apksigner จะพยายามถอดรหัสโดยใช้ข้อมูลของ รหัสผ่าน:

  • แบบฟอร์ม Unicode
  • แบบฟอร์มที่เข้ารหัสโดยใช้ชุดอักขระเริ่มต้น JVM
  • ใน Java 8 และเก่ากว่า แบบฟอร์มจะเข้ารหัสโดยใช้ชุดอักขระเริ่มต้นของคอนโซล

    • ใน Java 9 apksigner จะตรวจไม่พบชุดอักขระของคอนโซล คุณอาจต้องระบุ --pass-encoding เมื่อ โดยใช้รหัสผ่านที่ไม่ใช่ ASCII นอกจากนี้ คุณอาจต้องระบุตัวเลือกนี้กับ KeyStore ที่ เครื่องมือคีย์ที่สร้างขึ้นบนระบบปฏิบัติการอื่นหรือในภาษาอื่น

    --key-pass <input-format>

    รหัสผ่านสำหรับคีย์ส่วนตัวของผู้ลงนาม ซึ่งจำเป็นต้องใช้หาก คีย์ส่วนตัวมีการป้องกันด้วยรหัสผ่าน เครื่องมือ apksigner รองรับรูปแบบต่อไปนี้

    • pass:<password> – ป้อนรหัสผ่านในบรรทัด ด้วยคำสั่ง apksigner sign ที่เหลือ
    • env:<name> – รหัสผ่านจัดเก็บอยู่ใน ตัวแปรสภาพแวดล้อม
    • file:<filename> – รหัสผ่านจะจัดเก็บเป็น บรรทัดเดียวในไฟล์ที่กำหนด
    • stdin – รหัสผ่านจะแสดงเป็นบรรทัดเดียวใน สตรีมอินพุตมาตรฐาน นี่คือลักษณะการทำงานเริ่มต้นของ --key-pass
    --ks-type <algorithm>
    ประเภทหรืออัลกอริทึมที่เชื่อมโยงกับ KeyStore ซึ่งมี คีย์ส่วนตัวและใบรับรองของผู้ลงนาม โดยค่าเริ่มต้นคือ apksigner ใช้ประเภทที่กำหนดไว้เป็นค่าคงที่ keystore.type ในฟังก์ชัน ไฟล์คุณสมบัติความปลอดภัย
    --ks-provider-name <name>
    ชื่อผู้ให้บริการ JCA ที่จะใช้เมื่อขอ KeyStore ของผู้ลงนาม การใช้งานของคุณ โดยค่าเริ่มต้น apksigner จะใช้เมธอด ผู้ให้บริการที่มีลำดับความสำคัญสูงสุด
    --ks-provider-class <class-name>
    ชื่อคลาสที่มีคุณสมบัติครบถ้วนของผู้ให้บริการ JCA ที่จะใช้เมื่อส่งคำขอ การติดตั้งใช้งาน KeyStore ของผู้ลงนาม ตัวเลือกนี้ใช้เป็นทางเลือก ในราคา --ks-provider-name โดยค่าเริ่มต้นคือ apksigner ใช้ผู้ให้บริการที่ระบุด้วย --ks-provider-name ตัวเลือก
    --ks-provider-arg <value>
    ค่าสตริงที่จะส่งผ่านเป็นอาร์กิวเมนต์สำหรับเครื่องมือสร้างของ JCA คลาสของผู้ให้บริการ ระบบจะกำหนดคลาสด้วย --ks-provider-class โดยค่าเริ่มต้นคือ apksigner ใช้ตัวสร้างอาร์กิวเมนต์ศูนย์ของคลาส
    --key <filename>
    ชื่อไฟล์ที่มีคีย์ส่วนตัวของผู้ลงนาม ไฟล์นี้ ต้องใช้รูปแบบ PKCS #8 DER หากคีย์มีการป้องกันด้วยรหัสผ่าน apksigner แจ้งให้ป้อนรหัสผ่านโดยใช้อินพุตมาตรฐาน เว้นแต่คุณจะระบุรูปแบบอินพุตประเภทอื่นโดยใช้ --key-pass
    --cert <filename>
    ชื่อไฟล์ที่มีชุดใบรับรองของผู้ลงนาม ช่วงเวลานี้ ต้องใช้รูปแบบ X.509 PEM หรือ DER

    ยืนยันคำสั่ง

    คำสั่งยืนยัน apksigner มีตัวเลือกต่อไปนี้

    --print-certs
    แสดงข้อมูลเกี่ยวกับใบรับรองที่มีการรับรองของ APK
    --min-sdk-version <integer>
    ระดับ API เฟรมเวิร์ก Android ต่ำสุดที่ apksigner ใช้เพื่อ ให้ยืนยันว่าลายเซ็นของ APK จะได้รับการยืนยัน ค่าที่สูงขึ้นช่วยให้ เครื่องมือที่จะใช้พารามิเตอร์ความปลอดภัยที่เข้มงวดขึ้นเมื่อรับรองแอป แต่จำกัด ความพร้อมให้บริการของ APK สำหรับอุปกรณ์ที่ใช้ Android เวอร์ชันล่าสุด โดยค่าเริ่มต้น apksigner จะใช้ค่าของพารามิเตอร์ minSdkVersion จากไฟล์ Manifest ของแอป
    --max-sdk-version <integer>
    ระดับ API เฟรมเวิร์ก Android สูงสุดที่ apksigner ใช้ เพื่อยืนยันว่าลายเซ็นของ APK จะได้รับการยืนยัน โดยค่าเริ่มต้น เครื่องมือ ใช้ระดับ API สูงสุดเท่าที่จะเป็นไปได้
    -v, --verbose
    ใช้โหมดเอาต์พุตแบบละเอียด
    -Werr
    ถือว่าคำเตือนเป็นข้อผิดพลาด

    ตัวอย่าง

    ตัวอย่างการใช้ apksigner มีดังนี้

    ลงนาม APK

    ลงนาม APK โดยใช้ release.jks ซึ่งเป็นคีย์เดียวใน คีย์สโตร์: 

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

    ลงนาม APK โดยใช้คีย์ส่วนตัวและใบรับรองที่จัดเก็บเป็นไฟล์แยกกัน 

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

    ลงนาม APK โดยใช้คีย์ 2 อัน ได้แก่ 

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

    รับรอง APK ด้วยคีย์ Signing แบบหมุนเวียน และ SDK การกำหนดเป้าหมายการหมุนเวียนเวอร์ชัน 28 ขึ้นไป ดังนี้ 

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

    ลงนาม APK ด้วยคีย์ Signing แบบหมุนเวียน และ SDK การกำหนดเป้าหมายการหมุนเวียนเวอร์ชัน 33 ขึ้นไป: 

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

    ยืนยันลายเซ็นของ APK

    ตรวจสอบว่าลายเซ็นของ APK ควรได้รับการยืนยันว่าถูกต้องหรือไม่ใน แพลตฟอร์ม Android ทั้งหมดที่ APK สนับสนุน ได้แก่ 

    $ apksigner verify app.apk

    ตรวจสอบว่าลายเซ็นของ APK ควรได้รับการยืนยันว่าถูกต้องหรือไม่ใน Android 4.0.3 (API ระดับ 15) ขึ้นไป 

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

    หมุนเวียนคีย์การรับรอง

    เปิดใช้งานกลุ่มผู้รับใบรับรองที่มีการรับรองซึ่งรองรับการหมุนเวียนคีย์:

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

    หมุนเวียนคีย์การรับรองอีกครั้ง โดยทำดังนี้

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