3.2.0.0 버전부터 추가된 앱 서명 신원 검증 기능에 대한 설명입니다.
서명 신원 검증 기능을 사용하려면 앱 서명에 사용된 인증서의 SHA-256 인증서 지문(fingerprint) 값을 콘솔에 직접 입력해야 합니다. 아래 방법 중 본인의 서명 방식에 맞는 방법을 선택해 값을 확인하세요.
1. Google Play가 앱 서명을 관리하는 경우
Google Play가 앱 서명 키를 관리하고 있다면, 별도 명령어 실행 없이 콘솔 화면에서 값을 바로 확인할 수 있습니다.
메뉴 경로: 앱 선택 → Google Play로 보호됨 → Play 스토어 보호 → 앱 서명 키 보호 → Play 앱 서명 관리
※ Google Play Console 메뉴 개편으로 경로가 변경되었습니다. (기존: 앱 무결성 → Play 앱 서명 → 설정 → 앱 서명 키 인증서)
이동한 화면에서 앱 서명 키 및 업로드 키의 SHA-256 인증서 지문(MD5·SHA-1 포함) 값을 확인할 수 있습니다. 그중 SHA-256 값을 그대로 복사하여 사용하세요.
⚠️ 주의: 반드시 "앱 서명 키(App signing key)" 값을 등록하세요. 업로드 키(Upload key)는 개발자가 Play Console에 앱 번들을 업로드할 때 본인 확인용으로만 쓰이는 키이며, 실제 사용자 기기에 배포되는 APK는 구글이 보관하는 앱 서명 키로 서명됩니다. 따라서 서명 신원 검증에는 앱 서명 키의 SHA-256 값만 등록하면 되며, 업로드 키 값을 등록하면 런타임 검증이 실패할 수 있습니다.
2. 개발자가 서명 키를 직접 관리하는 경우
방법 A. 키스토어 파일에서 확인 (release keystore를 보유한 경우)
JDK keytool 명령어로 키스토어에서 인증서 정보를 조회하면 SHA-256 값을 확인할 수 있습니다.
필요 환경: JDK (Java Development Kit)
명령어 구조
keytool -list -v -alias {키 별칭} -keystore {키스토어 파일 경로}사용 예시
keytool -list -v -alias appsealing -keystore C:\AppSecurity\release.keystore명령 실행 시 키스토어 비밀번호 입력을 요구하며, 실행 결과의 Certificate fingerprints 항목 중 SHA256: 값을 콘솔에 입력합니다.
Certificate fingerprints:
SHA256: AB:CD:EF:12:34:...방법 B. 이미 서명된 APK/AAB 파일에서 확인 (키스토어에 접근할 수 없는 경우, 예: CI에서 서명한 빌드)
Android SDK build-tools에 포함된 apksigner 도구를 사용합니다.
명령어 구조
apksigner verify --print-certs {apk_또는_aab_파일_경로}사용 예시
apksigner verify --print-certs C:\AppSecurity\app-release.apk출력 결과 중 Signer #1 certificate SHA-256 digest 값을 콘솔에 입력합니다.
⚠️ 여러 서명자가 표시되는 경우: 서명 키 로테이션이 적용된 앱 등 둘 이상의 키로 서명된 경우, 출력 결과에
Signer #2 certificate SHA-256 digest처럼 추가 서명자가 함께 표시될 수 있습니다. 이 경우 표시된 모든 서명자의 SHA-256 값을 콘솔에 등록해야 런타임 검증 오류를 방지할 수 있습니다.
3. 콘솔 사용 예시
- 앱을 선택한 뒤, 3.2.0.0 이상 버전을 선택합니다.
- Step 2.기본 설정 메뉴에서 서명 인증서 신원 확인 체크박스를 활성화 합니다.
- 키를 식별할수 있는 이름을 입력후, SHA-256 해시를 입력 ( 콜론 구분자
:는 사용해도 무방합니다. ) - 항목 저장 버튼을 눌러 저장된것을 확인후 보안 적용을 진행합니다.
- 인증서 SHA-256 해시 정보는 최대 5개를 저장할수 있습니다. 개발용/배포용 서명키 등을 미리 등록하여 편리하게 사용하실 수 있습니다.
주의사항
- 인증서 불일치 시 앱 강제 종료: 콘솔에 등록한 SHA-256 값과 실제 배포된 앱의 서명 키 인증서가 일치하지 않으면, 해당 앱은 비공식 앱으로 간주되어 실행이 종료됩니다. 오탈자, 잘못된 키(업로드 키 등) 등록이 없는지 반드시 확인해 주세요.
- 내부 테스트/디버그 빌드도 등록 필요: 내부 테스트를 위해 디버그 키(debug.keystore)나 프로덕션과 다른 별도 릴리즈 키로 서명한 빌드를 배포하는 경우, 해당 키도 등록하지 않으면 테스트 단계에서 앱이 종료될 수 있습니다. 실제 기기에 설치되는 모든 빌드에 사용된 서명 키는 예외 없이 등록되어야 런타임 중단을 피할 수 있습니다.
-
여러 키로 서명된 앱: 하나의 앱이 둘 이상의 서명 키로 서명되어 있는 경우 (예: 서명 키 로테이션이 적용된 빌드),
apksigner verify --print-certs실행 시 Signer #1 외에 Signer #2 등 추가 서명자가 함께 출력될 수 있습니다. 이때는 출력된 모든 서명자의 SHA-256 값을 등록해야 합니다. - 서명 키를 교체(로테이션)하여 사용하는 경우: A 키에서 B 키로 서명 키를 교체하여 사용 중이거나 도입 예정이라면, 아래 문서를 통해 추가 주의사항을 반드시 숙지해 주세요.