از 27 مارس 2025، توصیه می کنیم از android-latest-release به جای aosp-main برای ساختن و کمک به AOSP استفاده کنید. برای اطلاعات بیشتر، به تغییرات AOSP مراجعه کنید.
با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
نمای کلی
اندروید 13 از طرح امضای APK نسخه 3.1 پشتیبانی می کند، که بهبودی در طرح امضای APK موجود نسخه 3 است. طرح v3.1 برخی از مشکلات شناخته شده APK Signature Scheme v3 در مورد چرخش را بررسی می کند. به طور خاص، طرح امضای v3.1 از هدف‌گیری نسخه SDK پشتیبانی می‌کند، که به چرخش اجازه می‌دهد تا نسخه بعدی پلتفرم را هدف قرار دهد.
طرح امضای نسخه 3.1 از شناسه بلوکی استفاده می‌کند که در اندروید 12 یا پایین‌تر شناسایی نمی‌شود. بنابراین، پلت فرم رفتار امضاکننده زیر را اعمال می کند:
دستگاه‌هایی که اندروید 13 یا بالاتر را اجرا می‌کنند، از امضاکننده چرخشی در بلوک نسخه 3.1 استفاده می‌کنند.
دستگاه‌هایی که نسخه‌های قدیمی‌تر اندروید را اجرا می‌کنند، امضاکننده چرخشی را نادیده می‌گیرند و در عوض از امضاکننده اصلی در بلوک v3 استفاده می‌کنند.
برنامه‌هایی که هنوز کلید امضای خود را چرخانده‌اند، نیازی به اقدام اضافی ندارند. هر زمان که این برنامه‌ها چرخش را انتخاب کنند، سیستم به‌طور پیش‌فرض طرح امضای v3.1 را اعمال می‌کند.
بلوک امضا نسخه 3.1
بلوک امضای نسخه 3.1 محتویات بلوک امضای نسخه 3 را دارد، اما با شناسه بلوک جدید، این امضاها فقط در دستگاه‌هایی که اندروید 13 و بالاتر دارند، شناسایی می‌شوند. این به برنامه‌ها اجازه می‌دهد تا کلیدهای امضای خود را بدون نگرانی در مورد APKهای چند هدفه بچرخانند، زیرا امضاکننده اصلی می‌تواند برای امضای APK در بلوک امضای v3 و امضاکننده چرخانده شده در بلوک امضای v3.1 استفاده شود. این همچنین به پلتفرم اجازه می‌دهد تا هنگام تأیید امضای v3.1 از همه کدهای تأیید موجود برای بلوک امضای v3 استفاده مجدد کند.
به‌طور پیش‌فرض، کتابخانه apksig از بلوک امضای v3.1 استفاده می‌کند، هر زمان که یک کلید چرخشی و دودمان در پیکربندی امضا ارائه شود. اگر minSdkVersion یک برنامه کمتر از Android 13 باشد و از یک کلید چرخشی استفاده شود، کلید امضای اصلی نیز باید مشخص شود تا بتوان از آن برای امضای APK در بلوک امضای v3 استفاده کرد. اگر APK نسخه‌ای زودتر از Android 9 را هدف قرار دهد، این شبیه رفتار فعلی است که امضاکننده اصلی لازم است.
برای پشتیبانی از چرخش کلید هدفمند که از یک نسخه SDK خاص شروع می شود، کتابخانه apksig API های جدیدی را نشان می دهد که اجازه می دهد حداقل نسخه SDK را برای چرخش تنظیم کنید اگر نسخه SDK کمتر از Android 13 به عنوان حداقل نسخه برای پشتیبانی از چرخش مشخص شده باشد، نسخه اصلی نسخه 3 مشخص شده است. بلوک استفاده خواهد شد. بلوک امضای نسخه 3.1 فقط در صورت وجود چرخش استفاده می‌شود که حداقل نسخه SDK برای چرخش روی Android 13 و بالاتر تنظیم شده است. بلوک امضای v3 دارای یک ویژگی جدید برای محافظت از حذف حداقل نسخه SDK با چرخش است.
APK شامل Lineage است
مقدار rotation-min-sdk-version
بلوک امضای v3
بلوک امضا نسخه 3.1
خیر
پیش فرض یا هر مقداری (که با x در زیر نشان داده شده است)
امضا شده با امضاکننده اصلی، اندروید 9 و بالاتر
حاضر نیست
بله
پیش فرض
امضا شده با امضا کننده اصلی، اندروید 9 تا 12L را هدف قرار می دهد
امضا شده با امضاکننده چرخشی که Android 13 و بالاتر را هدف قرار می‌دهد
بله
x < 33 (اندروید 13)
امضا شده با امضاکننده چرخشی، اندروید 9 و بالاتر را هدف قرار می‌دهد
حاضر نیست
بله
x >= 33 (اندروید 13)
امضا شده با امضاکننده اصلی، با هدف قرار دادن Android 9 - ( x -1)
امضا شده با امضا کننده چرخانده، x+ را هدف قرار می دهد
مسائل مربوط به چرخش
مشکلات مربوط به چرخش زیر در پلتفرم حل شده است:
رفع مشکلات اندروید 12
این پلتفرم تنها در صورتی مجوز امضا را به برنامه درخواست‌کننده می‌دهد که امضاکننده فعلی هر یک از برنامه‌ها در اصل امضاکننده باشد یا امضاکننده فعلی برنامه دیگر باشد. اگر این دو برنامه از بهترین شیوه های کلید امضا پیروی کنند و به کلیدهای امضای متفاوت بچرخند، این مانع از اعطای مجوز امضا به برنامه درخواست کننده می شود.
ویژگی بازگشت APK پلتفرم نمی‌تواند APK را که فقط کلید امضای آن چرخانده شده است، برگرداند، مگر اینکه کلید قبلی در خط امضا دارای قابلیت بازگشت باشد، اما این قابلیت هدف چرخش را شکست می‌دهد، زیرا امکان امضای به‌روزرسانی بسته جدید را می‌دهد. کلید امضای قبلی و بازگرداندن کلید چرخانده شده.
یک APK امضا شده فقط با کلید چرخانده شده و بعداً با یک APK امضا شده با کلید اصلی و کلید چرخانده شده در دودمان به‌روزرسانی می‌شود، فقط کلید چرخانده شده را در دودمان در دستگاه‌های دارای Android نسخه 11 و پیش‌تر نشان می‌دهد.
اصلاحات اندروید 11
PackageManager#checkSignatures برای بررسی کلیدهای امضای اصلی دو بسته به درستی به روز نشده است. این ابزار ابزار دقیق برنامه‌ها را با استفاده از کلید امضای چرخشی با APK ابزار دقیق با استفاده از کلید امضای اصلی شکست.
بسته‌های تحت یک sharedUserId دودمان امضای خود را به اشتراک می‌گذارند. هر زمان که یک برنامه با دودمان امضای به‌روزرسانی شده در یک sharedUiserId نصب یا به‌روزرسانی شود، اصل و نسب آن برنامه جایگزین اصل و نسب مشترک برای sharedUserId می‌شود (یعنی اگر خط امضای یک برنامه A -> B بود و یک برنامه در sharedUserId به‌روزرسانی می‌شد. با دودمان B -> C، سپس نسب sharedUserId با B -> C جایگزین می شود. به طور مشابه، قابلیت‌های امضاکننده قبلی در اصل و نسب نمی‌تواند به‌روزرسانی شود، مگر اینکه نسب امضا تغییر کند.
ادغام v4
طرح امضای v4 از پیکربندی امضای ارائه شده به apksigner استفاده می کند. در مورد تنظیمات امضای چندگانه ارائه شده برای چرخش، آخرین پیکربندی امضای چرخشی استفاده می شود. قبل از معرفی نسخه 3.1، نسخه 3 فقط شامل آخرین پیکربندی امضای چرخشی بود، بنابراین نسخه 4 می‌توانست از این پیکربندی همانطور که هست استفاده کند. با این کار، طرح امضای v4 می‌توانست از چرخش پشتیبانی کند، زیرا از کلید امضای چرخشی در SigningInfo خود استفاده می‌کرد. در حالی که v4 SigningInfo شامل دودمان امضای کامل نمی‌شود، می‌تواند آن را از بلوک امضای v3 بیرون بکشد تا به پلتفرم اجازه دسترسی به اصل و نسب را برای هرگونه درخواست امضا بدهد. هنگامی که نسخه 3.1 برای هدف قرار دادن چرخش برای نسخه ارائه شده rotation-min-sdk استفاده می شود، پیکربندی عمومی v3 هم پیکربندی امضای اصلی و هم آخرین پیکربندی امضای چرخش شده را شامل می شود. یک برنامه افزودنی از طرح امضای v4 ایجاد شده است که شامل بلوک های اطلاعات امضای اضافی برای هر یک از پیکربندی های امضا از بلوک v3.1 است.
اعتبار سنجی
برای آزمایش پیاده‌سازی نسخه 3.1، آزمایش‌های PkgInstallSignatureVerificationTest.java CTS را در cts/hostsidetests/appsecurity/src/android/appsecurity/cts/ اجرا کنید.
برای اطلاعات بیشتر در مورد آزمایش، بخش تأیید در نسخه 3 را بررسی کنید.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین به‌روزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","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-29 بهوقت ساعت هماهنگ جهانی."],[],[],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."]]
