موقّع ملفات APK

تتيح لك الأداة apksigner، المتوفّرة في الإصدار 24.0.3 والإصدارات الأحدث من أدوات إنشاء حزمة تطوير البرامج (SDK) لنظام التشغيل Android، توقيع حِزم 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، يجب تقديم المفتاح الخاص والشهادة الخاصة بالموقِّع. يمكنك تضمين هذه المعلومات بطريقتين:

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

استخدِم only لإنشاء توقيع v4 فقط بدون تعديل حزمة APK وأي توقيعات كانت تتضمّنها قبل الاستدعاء. يتعذّر تنفيذ only إذا لم يكن ملف APK يتضمّن توقيعًا بالإصدار 2 أو 3، أو إذا كان التوقيع يستخدم مفتاحًا مختلفًا عن المفتاح المقدَّم للاستدعاء الحالي.

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

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

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

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

--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. إذا كان KeyStore المرتبط بالموقِّع يحتوي على مفاتيح متعددة، يجب تحديد هذا الخيار.
--ks-pass <input-format>

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

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

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

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

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

  • شكل Unicode
  • النموذج بترميز مجموعة الأحرف التلقائية في JVM
  • في Java 8 والإصدارات الأقدم، يتم ترميز النموذج باستخدام مجموعة الأحرف التلقائية لوحدة التحكّم

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

    --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 verify الخيارات التالية.

    --print-certs
    عرض معلومات حول شهادات توقيع حِزم APK
    --print-certs-pem
    عرض معلومات حول شهادات توقيع حِزم APK وطباعة ترميز PEM لكل شهادة توقيع إلى الإخراج المعياري
    --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، وهو المفتاح الوحيد في ملف KeyStore: 

    $ 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 باستخدام مفتاح توقيع تم استبداله والإصدار المستهدف من حزمة تطوير البرامج (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 على الإصدار 4.0.3 من نظام التشغيل Android (المستوى 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