موقّع ملفات 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 لجميع وإصدارات النظام الأساسي السابقة. بشكل افتراضي، مفاتيح التوقيع بالتناوب المتاحة على الأجهزة التي تعمل بنظام التشغيل 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 المحدّدة. باستخدام ملف APK الإصدار 2 من مخطّط التوقيع بشكل افتراضي، تستخدم الأداة قيم --min-sdk-version و--max-sdk-version لاتخاذ قرار ومتى يتم تطبيق مخطط التوقيع هذا.
--v3-signing-enabled <true | false>
تحدِّد هذه السياسة ما إذا كان apksigner سيوقّع حزمة APK المحدّدة. باستخدام ملف APK الإصدار 3 من مخطّط التوقيع بشكل افتراضي، تستخدم الأداة قيم --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 لإنشاء الإصدار 4 فقط. التوقيع بدون تعديل حزمة 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 الذي يحتوي على المفتاح والشهادة لا يحتاج إلى ملف المحدد، وهو ما ينطبق على بعض متاجر مفاتيح PKCS #11.
--ks-key-alias <alias>
اسم الاسم المستعار الذي يمثل المفتاح الخاص للموقِّع الشهادة في ملف تخزين المفاتيح. إذا كان ملف تخزين المفاتيح المرتبط يحتوي الموقِّع على مفاتيح متعددة، فيجب تحديد هذا الخيار.
--ks-pass <input-format>

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

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

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

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

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

  • نموذج يونيكود
  • النموذج الذي تم ترميزه باستخدام مجموعة أحرف 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 باستخدام مفتاح توقيع تم تغييره وحزمة تطوير البرامج (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 باستخدام مفتاح توقيع تم تدويره وحزمة تطوير البرامج (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 (المستوى 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