اعتبارًا من 27 آذار (مارس) 2025، ننصحك باستخدام android-latest-release بدلاً من aosp-main لإنشاء AOSP والمساهمة فيه. لمزيد من المعلومات، يُرجى الاطّلاع على التغييرات في AOSP.
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
نظرة عامة
يتوافق نظام Android 13 مع الإصدار 3.1 من مخطّط توقيع حِزم APK، وهو
تحسين على الإصدار الحالي
من مخطّط توقيع حِزم APK
v3. يعالج المخطّط 3.1 بعض المشاكل المعروفة في الإصدار 3 من "مخطّط توقيع حزمة APK" في ما يتعلّق بالدوران. على وجه التحديد، يتيح مخطّط التوقيع في الإصدار 3.1 استهداف إصدار حزمة تطوير البرامج (SDK)، ما يسمح بالتناوب لتحديد إصدار أحدث من المنصة.
يستخدم نظام التوقيع في الإصدار 3.1 رقم تعريف حظْر لا يتم التعرّف عليه على الإصدار 12 من نظام التشغيل Android أو الإصدارات الأقدم. لذلك، تطبّق المنصة
سلوك الموقّع التالي:
تستخدم الأجهزة التي تعمل بالإصدار 13 من نظام التشغيل Android أو إصدار أحدث الموقّع المتغيّر في السلسلة المتعلّقة بالإصدار 3.1.
تتجاهل الأجهزة التي تعمل بإصدارات Android القديمة الموقّع الذي تم تدويره، ويُستخدَم بدلاً من ذلك الموقّع الأصلي في حزمة الإصدار 3.
لا تتطلّب التطبيقات التي لم يتم استبدال مفتاح توقيعها بعد أي
إجراء إضافي. عندما تختار هذه التطبيقات التبديل، يطبّق النظام مخطّط التوقيع v3.1
تلقائيًا.
وحدة التوقيع في الإصدار 3.1
ستتضمّن وحدة التوقيع في الإصدار 3.1 المحتوى نفسه المضمّن في وحدة التوقيع في الإصدار 3،
ولكن مع رقم تعريف الوحدة الجديد، لن يتم التعرّف على هذه التوقيعات
إلا على الأجهزة التي تعمل بالإصدار 13 من Android والإصدارات الأحدث.
يتيح ذلك للتطبيقات تغيير مفاتيح التوقيع بأمان بدون القلق بشأن ملفات APK المخصّصة لعدة أنظمة تشغيل، لأنّه يمكن استخدام الموقّع الأصلي لتوقيع حزمة APK في قالب التوقيع بالإصدار 3 وحزمة APK الموقّعة باستخدام الموقّع الذي تم تغييره في قالب التوقيع بالإصدار 3.1. ويسمح ذلك أيضًا ل
النظام الأساسي بإعادة استخدام جميع رموز التحقّق الحالية لوحدة التوقيع في الإصدار 3
عند التحقّق من توقيع الإصدار 3.1.
ستستخدم مكتبة apksig تلقائيًا ملف توقيع
الإصدار 3.1 كلما تم تقديم مفتاح متغيّر وسلسلة منشأ في إعدادات
التوقيع. إذا كان إصدار minSdkVersion للتطبيق أقل من Android 13 وكان يتم استخدام مفتاح متغيّر، يجب تحديد مفتاح التوقيع الأصلي أيضًا لكي يمكن استخدامه لتوقيع حزمة APK في قالب التوقيع بالإصدار 3. وهذا مشابه للسلوك الحالي الذي يتطلب
توقيع الموقّع الأصلي إذا كانت حزمة APK تستهدف إصدارًا أقدم من Android 9.
لتمكين ميزة استهداف تبديل المفاتيح بدءًا من إصدار معيّن من حزمة SDK،
ستوفّر مكتبة apksig واجهات برمجة تطبيقات جديدة تتيح
ضبط الحد الأدنى لإصدار حزمة SDK لتبديل المفاتيح. وإذا تم تحديد إصدار حزمة SDK أقل
من Android 13 كحد أدنى للإصدار المتوافق مع ميزة تبديل المفاتيح،
سيتم استخدام الإصدار الأصلي من الإصدار 3. لا يتم استخدام حزمة التوقيع v3.1 إلا في حال استخدام ميزة "التبديل السريع"، حيث يتم ضبط الحد الأدنى لإصدار حزمة SDK المتوافق مع ميزة "التبديل السريع" على Android 13 والإصدارات الأحدث. ستحتوي حزمة التوقيع من الإصدار 3 على سمة جديدة للاستبدال
لحماية من إزالة الحد الأدنى لإصدار حزمة تطوير البرامج (SDK).
تضمين Lineage في حزمة APK
قيمة rotation-min-sdk-version
وحدة التوقيع في الإصدار 3
وحدة التوقيع في الإصدار 3.1
لا
القيمة التلقائية أو أي قيمة (يتم تمثيلها بالرمز x أدناه)
تم التوقيع عليها باستخدام الموقّع الأصلي، وتستهدف الإصدار 9 من Android والإصدارات الأحدث
غير متوفّر
نعم
تلقائي
تم التوقيع باستخدام الموقّع الأصلي، ويستهدف الإصدارات من Android 9 إلى 12L
تم التوقيع باستخدام موقّع متغيّر، مع استهداف الإصدار 13 من نظام التشغيل Android والإصدارات الأحدث
نعم
x < 33 (Android 13)
تم التوقيع باستخدام موقّع متغيّر، مع استهداف الإصدار 9 من Android والإصدارات الأحدث
غير متوفّر
نعم
x >= 33 (Android 13)
تم التوقيع باستخدام الموقّع الأصلي، مع استهداف Android 9 (x-1)
تم التوقيع باستخدام موقّع تم تغييره، مع استهداف x+
المشاكل المتعلّقة بالدوران
تم حلّ المشاكل التالية المتعلّقة بالدوران في
النظام الأساسي:
إصلاحات Android 12
لن تمنح المنصة إذن التوقيع إلا للتطبيق الذي يطلب إذن التوقيع إذا كان ملف توقيع التطبيق المعنيّ في سلسلة التوقيع، أو كان ملف التوقيع الحالي للتطبيق الآخر، ما يمنع منح إذن التوقيع للتطبيق الذي يطلب إذن التوقيع إذا كان التطبيقان يتّبعان أفضل الممارسات المتعلّقة بمفاتيح التوقيع ويبدّلان مفاتيح التوقيع المختلفة.
لا يمكن ميزة التراجع عن تثبيت ملف APK في النظام الأساسي التراجع عن تثبيت ملف APK الذي تم
استبدال مفتاح توقيعه مؤخرًا ما لم يكن المفتاح السابق في سلسلة توقيعات التطبيق يمتلك
إمكانية التراجع، ولكن هذه الميزة تبطل الغرض من استبدال المفاتيح لأنّها
تسمح بتوقيع تحديث حزمة جديد باستخدام مفتاح التوقيع السابق
والتراجع عن استبدال المفتاح.
إذا تم توقيع حزمة APK باستخدام المفتاح الذي تم تغييره فقط وتم تعديلها لاحقًا باستخدام حزمة APK موقَّعة
بالمفتاح الأصلي والمفتاح الذي تم تغييره في السلسلة، لن تعرض سوى
المفتاح الذي تم تغييره في السلسلة على الأجهزة التي تعمل بالإصدار Android 11
والإصدارات الأقدم.
إصلاحات Android 11
لم يتم تعديل PackageManager#checkSignatures بشكل صحيح للتحقّق من
مفاتيح التوقيع الأصلية لحِزمتَين.
أدّى ذلك إلى إيقاف أداة تحليل الأداء للتطبيقات التي تستخدم مفتاح توقيع تم استبداله مع
حزمة APK الخاصة بأداة تحليل الأداء التي تستخدم مفتاح التوقيع الأصلي.
تشترك الحِزم ضمن sharedUserId في سلسلة التوقيع.
عند تثبيت تطبيق يتضمّن سلسلة مُحدَّثة لتوقيع التطبيق أو تعديله في
sharedUiserId، يتم استبدال سلسلة sharedUserId
المشترَكة بسلسلة sharedUserId
لهذا التطبيق (أي،
إذا كانت سلسلة توقيع التطبيق هي A -> B، وتم تعديل التطبيق في
sharedUserId باستخدام السلسلة B -> C، سيتم استبدال سلسلة sharedUserId
بسلسلة B -> C). وبالمثل، لا يمكن تعديل إمكانات موقّع سابق في سلسلة
النسب ما لم يتم تغيير سلسلة النسب الخاصة بالتوقيع.
دمج الإصدار 4
يستخدم مخطّط التوقيع في الإصدار 4 إعدادات التوقيع المقدَّمة إلى apksigner. في
حال توفُّر إعدادات توقيع متعدّدة لتغيير التوقيع، يتم استخدام أحدث إعدادات
التوقيع التي تم تغييرها. قبل طرح الإصدار 3.1، كان الإصدار 3 يتضمّن
فقط أحدث إعدادات التوقيع المتغيّر، لذلك تمكّن الإصدار 4 من استخدام هذه الإعدادات كما هي. وبفضل
هذا، تمكّن نظام التوقيع في الإصدار 4 من إتاحة إمكانية التبديل لأنّه استخدم
مفتاح التوقيع المتغيّر في SigningInfo. على الرغم من أنّ SigningInfo في الإصدار 4 لا يضمّن
سلسلة التوقيع الكاملة، يمكنه سحب هذا العنصر من قالب التوقيع
في الإصدار 3 للسماح للمنصة بالوصول إلى سلسلة التوقيع لأي طلبات بحث عن التوقيعات.
عند استخدام الإصدار 3.1 لاستهداف عملية التدوير لقيمة
rotation-min-sdk-version المقدَّمة، ستتضمّن إعدادات الإصدار 3 العامة كلّ من إعدادات
التوقيع الأصلية وأحدث إعدادات التوقيع التي تم تدويرها.
تم إنشاء إضافة لنظام توقيع الإصدار 4 تتضمّن مزيدًا من
كتل معلومات التوقيع لكلّ من إعدادات التوقيع من الإصدار 3.1.
التحقُّق
لاختبار عملية تنفيذ الإصدار 3.1، يمكنك إجراء
PkgInstallSignatureVerificationTest.java اختبارات CTS في
cts/hostsidetests/appsecurity/src/android/appsecurity/cts/.
لمزيد من المعلومات عن الاختبار، اطّلِع على قسم
التحقّق
في الإصدار 3.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# APK signature scheme v3.1\n\nOverview\n--------\n\nAndroid 13 supports APK signature scheme v3.1, an\nimprovement on the existing\n[APK signature scheme\nv3](/docs/security/features/apksigning/v3). The v3.1 scheme addresses some of the known issues with APK Signature\nScheme v3 regarding rotation. In particular, the v3.1\nsignature scheme supports SDK version targeting, which allows rotation to\ntarget a later release of the platform.\n\n\nThe v3.1 signature scheme uses a block ID that isn't recognized on Android\n12 or lower. Therefore, the platform applies the\nfollowing signer behavior:\n\n- Devices that run Android 13 or higher use the rotated signer in the v3.1 block.\n- Devices that run older versions of Android ignore the rotated signer and instead use the original signer in the v3 block.\n\nApps that haven't yet rotated their signing key don't require any additional\naction. Whenever these apps choose to rotate, the system applies the v3.1\nsignature scheme by default.\n\nv3.1 signing block\n------------------\n\nThe v3.1 signing block will have the same contents as the v3 signing block,\nbut with the new block ID these signatures\nwill only be recognized on devices running Android 13 and later.\nThis allows apps to safely rotate their signing keys without needing to worry about multi-target\nAPKs as the original signer can be used to sign the APK in the v3 signing\nblock and the rotated signer in the v3.1 signing block. This also allows the\nplatform to reuse all existing verification codes for the v3 signing block\nwhen verifying a v3.1 signature.\n\nBy default, the **apksig** library will use the\nv3.1 signing block whenever a rotated key and lineage is provided in the signing\nconfig. If an app's **minSdkVersion** is less than\nAndroid 13 and a rotated key is being used, the original signing key must be\nspecified as well so that it can be used to sign the APK in the v3 signing\nblock. This is similar to the current behavior where the original signer is\nrequired if the APK targets a version earlier than Android 9.\n\n\nTo support targeting key rotation starting from a particular SDK version,\nthe `apksig` library will expose new APIs that will allow\nsetting a minimum SDK version for rotation If an SDK version less\nthan Android 13 is specified as the minimum version for rotation support then\nthe original v3 block will be used. The v3.1 signing block is only used in the\npresence of rotation where the minimum SDK version for rotation is set to\nAndroid 13 and later. The v3 signing block will have a new attribute for rotation\nminimum SDK version stripping protection.\n\n| **APK Includes Lineage** | **Value of rotation-min-sdk-version** | **v3 signing block** | **v3.1 signing block** |\n|--------------------------|-------------------------------------------------|--------------------------------------------------------------|------------------------------------------------------------|\n| No | Default or any value (represented by *x* below) | Signed with original signer, targeting Android 9 and later | Not present |\n| Yes | Default | Signed with original signer, targeting Android 9 through 12L | Signed with rotated signer, targeting Android 13 and later |\n| Yes | *x* \\\u003c 33 (Android 13) | Signed with rotated signer, targeting Android 9 and later | Not present |\n| Yes | *x* \\\u003e= 33 (Android 13) | Signed with original signer, targeting Android 9 - (*x*-1) | Signed with rotated signer, targeting *x+* |\n\nRotation-related issues\n-----------------------\n\nThe following rotation-related problems have been resolved in the\nplatform:\n\n#### Android 12 fixes\n\n- The platform would only grant a signature permission to a requesting app if either app's current signer is in the signing lineage, or is the current signer, of the other app; this prevents granting a signature permission to a requesting app if the two apps follow signing key best practices and rotate to different signing keys.\n- The platform's APK rollback feature could not rollback an APK that just had its signing key rotated unless the previous key in the signing lineage had the rollback capability, but this capability defeats the purpose of rotation as it allows a new package update to be signed by the previous signing key and rolling back the rotated key.\n- An APK signed with only the rotated key and later updated with an APK signed with the original key and the rotated key in the lineage will only show the rotated key in the lineage on devices running Android 11 and earlier.\n\n#### Android 11 fixes\n\n- `PackageManager#checkSignatures` was not properly updated to check the original signing keys of two packages. This broke instrumentation for apps using a rotated signing key with the instrumentation APK using the original signing key.\n- Packages under a `sharedUserId` share their signing lineage. Whenever an app with an updated signing lineage is installed or updated in a `sharedUiserId` the lineage of that app replaced the shared lineage for the `sharedUserId` (that is, if an app's signing lineage were A -\\\u003e B, and an app is updated in the `sharedUserId` with lineage B -\\\u003e C, then the `sharedUserId` lineage would be replaced with B -\\\u003e C). Similarly capabilities of a previous signer in the lineage could not be updated unless the signing lineage were changed.\n| **Recommended:** It is recommended as part of best practices to rotate your app's signing key at least every **two** years.\n\nv4 integration\n--------------\n\nThe v4 signature scheme uses the signing config provided to apksigner; in the\ncase of multiple signing configs provided for rotation, the latest rotated\nsigning config is used. Prior to the introduction of v3.1, v3 only included this\nlatest rotated signing config, so v4 was able to use this config as is; with\nthis the v4 signature scheme was able to support rotation since it used the\nrotated signing key in its SigningInfo. While the v4 SigningInfo does not\ninclude the full signing lineage, it is able to pull this from the v3 signing\nblock to allow the platform access to the lineage for any signature queries.\nWhen v3.1 is in use to target rotation for the provided\nrotation-min-sdk-version, the generic v3 config will include both the original\nsigning config as well as the latest rotated signing config.\nAn extension of the v4 signature scheme has been created that includes additional\nsigning info blocks for each of the signing configs from the v3.1 block.\n\nValidation\n----------\n\n\nTo test your implementation of v3.1, run the\n`PkgInstallSignatureVerificationTest.java` CTS tests in\n`cts/hostsidetests/appsecurity/src/android/appsecurity/cts/`.\n\nFor more information about testing, check out the\n[verification](/docs/security/features/apksigning/v3#verification)\nsection in v3."]]
