موقّع ملفات APK

تتيح لك أداة apksigner المتوفّرة في الإصدار 24.0.3 والإصدارات الأحدث من أدوات إنشاء حزمة SDK لنظام التشغيل Android توقيع حِزم APK والتأكّد من أنّه سيتم التحقّق من توقيع ملف APK بنجاح على جميع إصدارات نظام Android الأساسي المتوافق مع حزمة APK هذه.

وتقدّم هذه الصفحة دليلاً موجزًا لاستخدام الأداة، كما تشكّل مرجعًا لخيارات سطر الأوامر المختلفة التي تتيحها الأداة. للحصول على وصف أكثر اكتمالاً لكيفية استخدام أداة apksigner لتوقيع حِزم APK، يمكنك الاطّلاع على توقيع تطبيقك.

تنبيه: إذا وقّعت حزمة APK باستخدام apksigner وأجريت تغييرات أخرى عليها، سيتم إبطال توقيع حزمة 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، يجب تقديم المفتاح الخاص والشهادة للموقِّع. ويمكنك تضمين هذه المعلومات بطريقتَين:

  • حدِّد ملف تخزين المفاتيح باستخدام الخيار --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>
أدنى مستوى لواجهة برمجة التطبيقات لإطار عمل Android الذي يستخدمه apksigner لتأكيد أنه سيتم التحقق من توقيع حزمة APK. وتتيح القيم الأعلى للأداة استخدام مَعلمات أمان أقوى عند توقيع التطبيق، ولكنّها تحصر مدى توفّر حزمة APK على الأجهزة التي تعمل بإصدارات أحدث من Android. يستخدم apksigner تلقائيًا قيمة السمة minSdkVersion من ملف البيان الخاص بالتطبيق.
--max-sdk-version <integer>
أعلى مستوى لواجهة برمجة تطبيقات إطار عمل Android يستخدمه apksigner لتأكيد أنّه سيتم التحقّق من توقيع حزمة APK. تستخدم الأداة تلقائيًا أعلى مستوى ممكن من واجهة برمجة التطبيقات.
--rotation-min-sdk-version <integer>
أدنى مستوى لواجهة برمجة التطبيقات يجب أن يستخدمه مفتاح التوقيع الذي تم تدويره لحزمة APK لإنشاء توقيع حزمة APK. سيتم استخدام مفتاح التوقيع الأصلي (غير المعدّل) لحزمة APK في جميع الإصدارات السابقة الخاصة بالأنظمة الأساسية. وفقًا للإعدادات التلقائية، يتم استخدام مفاتيح التوقيع الدورية والمتوافقة مع الأجهزة التي تعمل بالإصدار 13 من نظام التشغيل Android 13 (المستوى 33 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث مع مجموعة التوقيع 3.1.

ملاحظة: إذا تم توقيع تطبيقك باستخدام مفتاح توقيع تم تدويره على جهاز يعمل بنظام التشغيل Android 12L (المستوى 32 لواجهة برمجة التطبيقات) أو أقل، عليك استخدام --rotation-min-sdk-version 28 لمواصلة توقيع تطبيقك باستخدام مفتاح التوقيع الذي تم تدويره لنظام التشغيل Android 9 (مستوى واجهة برمجة التطبيقات 28).

--v1-signing-enabled <true | false>
تحدِّد هذه السياسة ما إذا كان apksigner سيوقّع حزمة APK المحدّدة باستخدام نظام التوقيع التقليدي المستند إلى JAR. بشكل تلقائي، تستخدم الأداة قيمتَي --min-sdk-version و--max-sdk-version لتحديد وقت تطبيق مخطط التوقيع هذا.
--v2-signing-enabled <true | false>
تحدِّد هذه السياسة ما إذا كان apksigner سيوقّع حزمة APK المحدّدة باستخدام الإصدار 2 من مخطّط توقيع APK. بشكل تلقائي، تستخدم الأداة قيمتَي --min-sdk-version و--max-sdk-version لتحديد وقت تطبيق مخطط التوقيع هذا.
--v3-signing-enabled <true | false>
تحدِّد هذه السياسة ما إذا كان apksigner سيوقّع حزمة APK المحدّدة باستخدام الإصدار 3 من مخطّط توقيع APK. بشكل تلقائي، تستخدم الأداة قيمتَي --min-sdk-version و--max-sdk-version لتحديد وقت تطبيق مخطط التوقيع هذا.
--v4-signing-enabled <true | false | only>

تحدِّد هذه السياسة ما إذا كان apksigner سيوقّع حزمة APK المحدّدة باستخدام الإصدار 4 من مخطّط توقيع APK. ينشئ هذا النظام توقيعًا في ملف منفصل (apk-name.apk.idsig). في حال عدم توقيع true وحزمة APK، سيتم إنشاء توقيع بالإصدار 2 أو v3 استنادًا إلى قيمتَي --min-sdk-version و--max-sdk-version. ينشئ الأمر بعد ذلك ملف .idsig استنادًا إلى محتوى حزمة APK الموقَّعة.

يمكنك استخدام only لإنشاء توقيع الإصدار 4 فقط بدون تعديل حزمة APK وأي توقيعات حصلت عليها قبل الاستدعاء. يتعذّر تنفيذ only إذا لم يكن لحزمة APK توقيع من النوع v2 أو v3 أو إذا استخدم التوقيع مفتاحًا مختلفًا عن المفتاح المتوفر للاستدعاء الحالي.

بشكل تلقائي، تستخدم الأداة قيمتَي --min-sdk-version و--max-sdk-version لتحديد وقت تطبيق مخطط التوقيع هذا.

-v، --verbose
استخدِم وضع الإخراج الصوتي المطوَّل.

خيارات كل موقِّع

تحدد الخيارات التالية إعدادات موقِّع معيّن. هذه الخيارات غير ضرورية في حال توقيع تطبيقك باستخدام موقِّع واحد فقط.

--next-signer <signer-options>
يُستخدم لتحديد خيارات عامة مختلفة لكل موقِّع.
--v1-signer-name <basename>
الاسم الأساسي للملفات التي تشكّل التوقيع المستند إلى JAR للموقِّع الحالي. يستخدم apksigner تلقائيًا الاسم المستعار للمفتاح الخاص بمخزن المفاتيح أو الاسم الأساسي لملف المفتاح الخاص بالموقِّع هذا.

خيارات المفتاح والشهادة

تحدد الخيارات التالية المفتاح الخاص والشهادة للموقِّع:

--ks <filename>
يتوفر المفتاح الخاص وسلسلة الشهادات للموقِّع في ملف KeyStore المستند إلى لغة Java. وإذا تم ضبط اسم الملف على "NONE"، لن يحتاج ملف تخزين المفاتيح الذي يتضمن المفتاح والشهادة إلى تحديد ملف، وهذا ما ينطبق على بعض حِزم PKCS #11 KeyStores.
--ks-key-alias <alias>
تشير هذه السمة إلى اسم العنوان البديل الذي يمثّل المفتاح الخاص للموقِّع وبيانات الشهادة في ملف KeyStore. إذا كان ملف تخزين المفاتيح المرتبط بالمُوقِّع يحتوي على مفاتيح متعدّدة، يجب تحديد هذا الخيار.
--ks-pass <input-format>

هي كلمة مرور ملف KeyStore الذي يحتوي على المفتاح الخاص والشهادة الخاصة بالموقِّع. يجب تقديم كلمة مرور لفتح ملف تخزين المفاتيح. تتيح أداة apksigner استخدام التنسيقات التالية:

  • pass:<password>: تم إدخال كلمة المرور بشكل مضمَّن مع باقي الأمر apksigner sign.
  • env:<name> – يتم تخزين كلمة المرور في متغير البيئة المحدّد.
  • file:<filename> – يتم تخزين كلمة المرور كسطر واحد في الملف المحدّد.
  • stdin – يتم توفير كلمة المرور كسطر واحد في مصدر الإدخال العادي. هذا هو السلوك التلقائي لنطاق --ks-pass.

ملاحظة: في حال تضمين عدة كلمات مرور في الملف نفسه، يجب تحديدها في أسطر منفصلة. تربط أداة apksigner كلمات المرور بموقِّعي حِزم APK بناءً على الترتيب الذي تحدِّد به الموقِّعين. في حال تقديم كلمتَي مرور لموقِّع، سيفسّر apksigner كلمة المرور الأولى على أنها كلمة مرور ملف تخزين المفاتيح والثانية باعتبارها كلمة المرور الرئيسية.

--pass-encoding <charset>
تتضمن ترميزات الأحرف المحددة، مثل ibm437 أو utf-8، عند محاولة التعامل مع كلمات المرور التي تحتوي على أحرف غير ASCII.

غالبًا ما تشفّر أداة Keytool ملفات تخزين المفاتيح من خلال تحويل كلمة المرور باستخدام مجموعة الأحرف التلقائية لوحدة التحكّم. يحاول apksigner تلقائيًا فك تشفير الرسالة باستخدام عدة أشكال من كلمة المرور:

  • نموذج Unicode
  • يشير هذا المصطلح إلى النموذج الذي تم ترميزه باستخدام مجموعة أحرف JVM التلقائية.
  • في Java 8 والإصدارات الأقدم، تم ترميز النموذج باستخدام مجموعة الأحرف الافتراضية لوحدة التحكم
  • في Java 9، لا يستطيع "apksigner" رصد مجموعة الأحرف في وحدة التحكّم. قد تحتاج إلى تحديد --pass-encoding عند استخدام كلمة مرور بتنسيق غير ASCII. وقد تحتاج أيضًا إلى تحديد هذا الخيار من خلال ملفات تخزين المفاتيح التي أنشأتها أداة المفاتيح على نظام تشغيل مختلف أو بلغة مختلفة.

    --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 لاستخدامه عند طلب تنفيذ ملف تخزين المفاتيح لدى الموقِّع. بشكل تلقائي، يستخدم 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>
    أدنى مستوى لواجهة برمجة التطبيقات لإطار عمل Android الذي يستخدمه apksigner لتأكيد أنه سيتم التحقق من توقيع حزمة APK. وتتيح القيم الأعلى للأداة استخدام مَعلمات أمان أقوى عند توقيع التطبيق، ولكنّها تحصر مدى توفّر حزمة APK على الأجهزة التي تعمل بإصدارات أحدث من Android. يستخدم apksigner تلقائيًا قيمة السمة minSdkVersion من ملف البيان الخاص بالتطبيق.
    --max-sdk-version <integer>
    أعلى مستوى لواجهة برمجة تطبيقات إطار عمل Android يستخدمه apksigner لتأكيد أنّه سيتم التحقّق من توقيع حزمة APK. تستخدم الأداة تلقائيًا أعلى مستوى ممكن من واجهة برمجة التطبيقات.
    -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 باستخدام مفتاحَين:

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

    وقِّع حزمة APK باستخدام مفتاح توقيع تم تدويره والإصدار 28 من حزمة تطوير البرامج (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 باستخدام مفتاح توقيع تم تدويره والإصدار 33 من حزمة تطوير البرامج (SDK) لاستهداف العرض بالتناوب أو الإصدارات الأحدث:

    $ 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 (المستوى 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