Android 13은 기존 APK 서명 체계 v3을 개선한 APK 서명 체계 v3.1을 지원합니다. v3.1 체계는 순환과 관련된 APK 서명 체계 v3의 알려진 문제 중 일부를 해결합니다. 특히 v3.1 서명 체계는 SDK 버전 타겟팅을 지원하므로, 순환에서 플랫폼의 최신 버전을 타겟팅할 수 있습니다.
v3.1 서명 체계는 Android 12 이하에서 인식되지 않는 블록 ID를 사용합니다. 따라서 플랫폼은 다음과 같은 signer 동작을 적용합니다.
Android 13 이상을 실행하는 기기는 v3.1 블록의 순환된 signer를 사용합니다.
Android 이전 버전을 실행하는 기기는 순환된 signer를 무시하고 v3 블록의 원래 signer를 사용합니다.
아직 서명 키를 순환하지 않은 앱에는 추가 작업이 필요하지 않습니다. 이러한 앱이 순환할 때마다 시스템은 기본적으로 v3.1 서명 체계를 적용합니다.
v3.1 서명 블록
v3.1 서명 블록은 v3 서명 블록과 콘텐츠가 동일하지만 새 블록 ID를 사용하면 이러한 서명이 Android 13 이상을 실행하는 기기에서만 인식됩니다.
이렇게 하면 앱이 다중 타겟 APK에 관해 걱정할 필요 없이 서명 키를 안전하게 순환할 수 있습니다. 원래 signer를 v3 서명 블록의 APK에 서명하는 데 사용하고 v3.1 서명 블록에는 순환된 signer를 사용할 수 있기 때문입니다. 또한 v3.1 서명을 인증할 때 플랫폼에서 v3 서명 블록의 모든 기존 인증 코드를 재사용할 수 있습니다.
기본적으로 apksig 라이브러리는 순환된 키와 계보가 서명 구성에 제공될 때마다 v3.1 서명 블록을 사용합니다. 앱의 minSdkVersion이 Android 13보다 낮고 순환된 키를 사용 중인 경우 v3 서명 블록의 APK에 서명하는 데 사용할 수 있도록 원래 서명 키도 지정해야 합니다. 이는 APK가 Android 9 미만 버전을 타겟팅하는 경우 원래 signer가 필요한 현재 동작과 유사합니다.
특정 SDK 버전부터 키 순환 타겟팅을 지원하기 위해 apksig 라이브러리는 순환을 위한 최소 SDK 버전을 설정할 수 있는 새 API를 노출합니다. Android 13 미만의 SDK 버전이 순환 지원의 최소 버전으로 지정되어 있으면 원래 v3 블록이 사용됩니다. v3.1 서명 블록은 순환을 위한 최소 SDK 버전이 Android 13 이상으로 설정된 순환이 있는 경우에만 사용됩니다. v3 서명 블록에는 순환 최소 SDK 버전 제거 보호를 위한 새로운 속성이 있습니다.
APK에 계보가 포함됨
rotation-min-sdk-version 값
v3 서명 블록
v3.1 서명 블록
아니요
기본값 또는 임의의 값(아래 x로 표시)
원래 signer로 서명되었으며 Android 9 이상을 타겟팅
없음
예
기본값
원래 signer로 서명되었으며 Android 9~12L을 타겟팅
순환된 signer로 서명되었으며 Android 13 이상을 타겟팅
예
x < 33(Android 13)
순환된 signer로 서명되었으며 Android 9 이상을 타겟팅
없음
예
x >= 33(Android 13)
원래 signer로 서명되었으며 Android 9~(x-1)을 타겟팅
순환된 signer로 서명되었으며 x+를 타겟팅
순환 관련 문제
다음과 같은 순환 관련 문제가 플랫폼에서 해결되었습니다.
Android 12 수정사항
플랫폼은 앱의 현재 signer가 다른 앱의 서명 계보에 있거나 다른 앱의 현재 signer인 경우에만 요청하는 앱에 서명 권한을 부여합니다. 이렇게 하면 두 앱이 서명 키 권장사항을 따르고 다른 서명 키로 순환하는 경우 요청하는 앱에 서명 권한을 부여하는 것을 방지할 수 있습니다.
플랫폼의 APK 롤백 기능은 서명 계보의 이전 키에 롤백 기능이 없는 경우 서명 키만 순환한 APK를 롤백할 수 없습니다. 하지만 이 기능은 새 패키지 업데이트가 이전 서명 키로 서명되고, 순환된 키로 롤백할 수 있으므로 순환의 목적을 무효화합니다.
순환된 키로만 서명되고 나중에 계보의 원래 키와 순환된 키로 서명된 APK로 업데이트된 APK는 Android 11 이하를 실행하는 기기의 계보에 순환된 키만 표시합니다.
Android 11 수정사항
두 패키지의 원래 서명 키를 확인하도록 PackageManager#checkSignatures가 제대로 업데이트되지 않았습니다.
이로 인해 원래 서명 키를 사용하는 계측 APK와 함께 순환된 서명 키를 사용하는 앱의 계측이 중단되었습니다.
sharedUserId 아래의 패키지는 서명 계보를 공유합니다.
업데이트된 서명 계보가 있는 앱이 sharedUiserId에서 설치되거나 업데이트될 때마다 앱의 계보가 sharedUserId의 공유 계보를 대체했습니다. 즉, 앱의 서명 계보가 A -> B이고 sharedUserId에서 계보 B -> C로 앱이 업데이트되는 경우 sharedUserId 계보는 B -> C로 대체됩니다. 마찬가지로 계보에 있는 이전 signer의 기능은
서명 계보가 변경되지 않는 한 업데이트할 수 없습니다.
v4 통합
v4 서명 체계는 apksigner에 제공된 서명 구성을 사용합니다. 순환을 위해 여러 서명 구성이 제공된 경우 마지막으로 순환된 서명 구성이 사용됩니다. v3.1 도입 전에 v3에는 마지막으로 순환된 이 서명 구성만 포함되었으므로 v4는 이 구성을 그대로 사용할 수 있었습니다. 이를 통해 v4 서명 체계는 순환을 지원할 수 있었습니다. SigningInfo에서 순환된 서명 키를 사용했기 때문입니다. v4 SigningInfo에는 전체 서명 계보가 포함되지 않지만 v3 서명 블록에서 이 정보를 가져와 플랫폼이 모든 서명 쿼리의 계보에 액세스하도록 허용할 수 있습니다.
v3.1이 제공된 rotation-min-sdk-version의 순환을 타겟팅하는 데 사용되는 경우 일반 v3 구성에는 원래 서명 구성과 마지막으로 순환된 서명 구성이 모두 포함됩니다.
v4 서명 체계의 확장 프로그램이 만들어졌으며 이 확장 프로그램은 v3.1 블록의 각 서명 구성에 관한 추가 서명 정보 블록을 포함합니다.
유효성 검사
v3.1 구현을 테스트하려면 cts/hostsidetests/appsecurity/src/android/appsecurity/cts/에서 PkgInstallSignatureVerificationTest.java CTS 테스트를 실행하세요.
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-07-27(UTC)
[[["이해하기 쉬움","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(UTC)"],[],[],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."]]
