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