앱 서명 키를 A 키에서 B 키로 교체(rotation)하여 사용 중이거나 도입 예정이라면, 서명 신원 검증 기능이 정상 동작하도록 아래 내용을 반드시 확인해 주세요.
시나리오: A 키로 서명하던 앱을 B 키로 교체
1. 최초 배포 시점 (A 키만 사용)
- AppSecurity 적용 (A 키 등록 및 번들)
- A 키로 서명하여 배포 및 설치
- 런타임에서 A 키 기준으로 서명 검증
2. B 키로 위임하여 배포하는 경우
- AppSecurity 적용 (A 키, B 키 모두 등록 및 번들)
- APK를 A 키 + B 키 + key lineage(서명 인증서 계보)로 서명
- 런타임에 관측되는 서명 키는 기기의 Android 버전에 따라 달라짐 (아래 "OS 버전별 동작" 참고)
서명 키 교체 명령어 예시
apksigner의 rotate 서브커맨드로 계보(lineage) 파일을 먼저 생성한 뒤, sign 커맨드에서 새 키(B)와 계보 파일을 함께 사용해 서명합니다.
1) 계보(lineage) 파일 생성
apksigner rotate --out lineage.bin \
--old-signer --ks A.keystore \
--new-signer --ks B.keystore
2) 새 키로 서명 (계보 파일 포함)
apksigner sign --ks B.keystore \
--next-signer --ks C.keystore \
--lineage lineage.bin \
app-release.apk
--next-signer는 향후 또 다른 키(C)로 재교체할 계획이 있을 때 사용하는 옵션이며, 이번에 B 키까지만 교체한다면 생략해도 됩니다. 서명된 APK의 v1/v2 블록에는 원본 서명자(A 키)의 서명만 포함되고, v3(및 v3.1) 블록에 B 키의 서명과 "A 키의 신뢰를 B 키가 상속받았다"는 계보 증명이 함께 담기는 방식입니다. A, B 두 키가 같은 블록에 나란히 서명하는 것이 아니라는 점에 유의하세요.
OS 버전별 동작: "설치/업데이트에 따라 다르다"는 것의 정확한 의미
같은 APK, 같은 Android 버전이라면 최초 설치든 업데이트든 런타임에 관측되는 서명 키는 동일합니다. 실제로 설치/업데이트 여부가 좌우하는 것은 OS의 설치 허용 여부이고(계보 파일 없이 B 키만으로 서명하면, 기존에 A 키로 설치된 앱에 대한 업데이트 자체가 서명 불일치로 거부됩니다), 런타임에 어떤 키가 유효하다고 관측되느냐는 Android 버전이 결정합니다.
- Android 8.1 이하 (API 27 이하): APK 서명 스킴 v3를 지원하지 않아 계보(rotation) 확장을 이해하지 못하고, 항상 v1/v2 블록에 담긴 원본 서명자(A 키) 로 검증합니다.
- Android 9 이상 (API 28 이상): v3를 지원하여 계보를 인식하고 B 키로 검증합니다. (단, 아래 v3.1 관련 유의사항 참고)
AppSecurity는 이렇게 OS가 실제로 읽어들인 서명 키 정보가 등록·번들되어 있는지만 확인합니다. 즉, A/B 키가 모두 등록되어 있어야 어떤 Android 버전의 기기에서도 서명 변조로 오탐되지 않습니다.
주의: APK 서명 스킴 v3.1 및 build-tools 버전에 따른 차이
Android SDK build-tools 33 이상에 포함된 apksigner는 별도 옵션이 없으면 교체된(새) 키 정보를 v3가 아닌 v3.1 블록(Android 13 / API 33 이상 전용)에 담습니다. 이 경우:
- Android 9 ~ 12L (API 28~32): v3 블록 기준 A 키(원본 서명자) 로 관측
- Android 13 이상 (API 33 이상): v3.1 블록 기준 B 키(교체된 서명자) 로 관측
즉 "API 28 이상이면 무조건 B 키로 관측된다"고 단정할 수 없으며, 실제 관측 키는 apksigner 버전과 옵션에 따라 달라집니다. API 28~32 기기에서도 B 키로 관측되게 하려면 서명 시 --rotation-min-sdk-version 옵션으로 낮은 API 레벨을 명시해야 합니다.
apksigner sign --ks B.keystore \
--lineage lineage.bin \
--rotation-min-sdk-version 28 \
app-release.apk
이 옵션·버전 차이까지 정확히 구분해 대응하기 어렵다면, A 키와 B 키를 모두 AppSecurity에 등록해 두는 것이 가장 안전합니다. API 28 이상의 기기에서 앱 서명키가 A키로 보이는 문제가 발생한다면, 대부분 이 v3/v3.1 블록 차이 때문입니다.
반드시 확인해야 할 사항
키 교체(로테이션) 시나리오를 사용하는 경우, 모든 플랫폼에서 안정적으로 동작하려면 앱을 A 키 + B 키로 함께 서명해야 합니다.
키 교체 이후에도 A 키와 B 키를 함께 계속 등록·유지하는 것이 안전합니다. 전환 기간이 끝났다고 이전 키(A) 등록을 해제하면, 구버전 OS나 아직 업데이트되지 않은 기기에서는 여전히 A 키로 검증되는 상황이 남아 있어 서명 변조로 오탐될 위험이 있습니다. A 키 등록은 임의로 해제하지 마세요.
체크리스트
- [ ] 키 교체(로테이션)를 사용 중인가?
- [ ] 사용 중이라면 A 키, B 키를 모두 AppSecurity에 등록했는가? (교체 이후에도 계속 유지)
- [ ] A 키, B 키 + lineage로 정상 서명된 빌드로 배포하고 있는가?
- [ ] build-tools 버전 및
--rotation-min-sdk-version설정에 따라 OS 버전별 관측 키가 달라질 수 있음을 인지하고 있는가?
위 항목을 모두 충족하지 않으면 일부 사용자 환경(특정 OS 버전, 설치/업데이트 조합)에서 정상 서비스가 차단될 수 있으니 반드시 사전에 확인해 주세요.