أداة 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.
--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
- استخدام وضع عرض النتائج المطوَّلة
ملاحظة: إذا تم توقيع تطبيقك من خلال عملية توقيع متناوبة
على جهاز يعمل بالإصدار Android 12L (المستوى 32 لواجهة برمجة التطبيقات) أو بإصدار أقدم،
يجب استخدام "--rotation-min-sdk-version 28
" لمواصلة التوقيع.
تطبيقك باستخدام مفتاح التوقيع المتغير لنظام Android 9 (المستوى 28 من واجهة برمجة التطبيقات).
خيارات كل موقِّع
تحدد الخيارات التالية إعدادات موقِّع معيّن. هذه لن تكون الخيارات ضرورية في حال توقيع تطبيقك باستخدام موقِّع واحد فقط.
--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