Keystore: 정의, 형식 및 작동 방식

Keystore란

Keystore(KeyStore)는 암호화 키, 인증서 및 신뢰할 수 있는 항목을 저장하기 위한 Java Cryptography Architecture(JCA)의 표준 메커니즘입니다. Android 개발에서 Keystore는 게시 전에 앱에 서명하는 개인 키를 저장하는 데 사용됩니다. 서명은 앱이 지정된 개발자에 의해 실제로 게시되었으며 게시 후 코드가 변경되지 않았음을 보장합니다. 모든 앱 업데이트는 동일한 키로 서명해야 하며, 그렇지 않으면 Google Play에서 APK 또는 App Bundle을 거부합니다.

Keystore에는 여러 항목(별칭)이 포함될 수 있으며, 각 항목은 인증서가 있는 키 쌍(개인 및 공개)을 나타냅니다. 별칭(Alias)은 서명 중에 앱이 키에 액세스하는 고유한 항목 이름입니다. 일반적인 Android 프로젝트에서 Keystore에는 릴리스 버전 서명을 위한 하나의 항목이 포함되어 있으며 디버그 빌드 서명을 위한 추가 항목이 포함될 수 있습니다. Google Play Console은 업로드된 각 앱의 SHA-1 및 SHA-256 인증서 지문을 표시합니다.

Android Studio는 Build → Generate Signed Bundle / APK 메뉴를 통해 Keystore에 대한 기본 제공 지원을 포함합니다. Android Studio의 서명 마법사를 사용하면 새 Keystore를 만들거나 기존 항목을 선택하고, 별칭, Keystore 및 키 비밀번호, 인증 데이터(조직 이름, 도시, 국가)를 지정할 수 있습니다. 이 데이터는 인증서에 포함되며 APK 서명 확인 시 사용자에게 표시됩니다. Google Play는 인증서가 최소 25년 동안 유효해야 합니다 — Android는 앱 설치 시 만료 날짜를 확인합니다.

Android에서 Keystore가 중요한 이유

Google Play에서의 앱 업데이트는 첫 번째 버전에 서명한 동일한 키로만 가능합니다. Keystore를 분실하면 업데이트를 게시할 수 없습니다 — 앱을 다른 패키지 이름으로 다시 게시해야 합니다. Google Play Console Help(2026)에 따르면, 앱 서명 키는 Google Play App Signing(키를 Google 측에 저장하는 서비스)을 통해서만 복구할 수 있습니다. 개발자가 이 옵션을 사용한 경우 로컬 Keystore를 분실해도 심각하지 않습니다.

Keystore의 작동 방식

Android 앱 서명 프로세스는 APK 콘텐츠의 다이제스트(해시)를 생성하고 Keystore의 개인 키로 암호화하는 것을 포함합니다. Android SDK Build Tools에는 APK Signature Scheme v2(또는 Android 9+의 경우 v3)를 사용하여 서명을 수행하는 apksigner 유틸리티가 포함되어 있습니다. 앱 설치 시 Android는 서명을 확인합니다. 인증서의 공개 키로 서명을 해독하고 APK 해시를 원본과 비교합니다 — 해시가 일치하지 않으면 설치가 거부됩니다.

Android는 여러 서명 체계를 지원합니다: v1(JAR 서명), v2(APK Signature Scheme), v3(키 순환 지원이 있는 APK Signature Scheme) 및 v4(Android 11+의 증분 설치)입니다. Google Play는 새 앱에 v2 또는 v3를 요구합니다. apksigner는 키가 해당 알고리즘을 지원하는 경우 서명 중에 필요한 모든 체계를 자동으로 추가합니다. Android 11+는 v4 서명을 사용한 ADB 설치를 지원하여 대용량 APK를 기기에 증분 로드하는 속도를 높입니다.

알고리즘: Android는 서명 키에 RSA-2048 또는 ECDSA P-256을 사용할 것을 권장합니다. 인증서는 X.509 v3이어야 합니다. Android는 설치 시 인증서가 유효한지 확인합니다 — 만료된 경우 설치가 차단됩니다. 이것이 Google이 인증서 유효 기간을 최소 25년으로 설정할 것을 권장하는 이유입니다. Google Play App Signing은 두 개의 키를 사용합니다: 앱 서명 키(app signing key)와 업로드 키(upload key)입니다 — 개발자는 업로드 키를 사용하여 Console에 APK를 업로드하고, Google은 기본 키로 사용자를 위해 앱에 서명합니다.

Keystore 형식: JKS와 PKCS12

Java는 두 가지 주요 Keystore 형식을 지원합니다: JKS(Java KeyStore) — JDK 1.2부터 존재하는 Oracle의 독점 형식, 그리고 PKCS12 — RSA Laboratories의 표준화된 Public-Key Cryptography Standards #12 형식입니다. JKS는 자체 데이터 저장 형식을 사용하며 Java 생태계 내에서만 지원됩니다. PKCS12는 Java, .NET, OpenSSL, Python(cryptography) 및 대부분의 다른 암호화 라이브러리에서 지원되는 개방형 표준입니다.

Google Play는 2021년 이후에 생성된 새 Keystore에 PKCS12를 선호 형식으로 권장합니다. JDK 9 이상은 기본적으로 PKCS12 형식으로 Keystore를 생성합니다(이전에는 JKS가 기본값이었습니다). PKCS12의 주요 장점은 호환성입니다. .p12 파일은 Java에 종속되지 않은 모든 환경에서 열 수 있습니다. OpenSSL은 PKCS12에서 인증서를 추출하여 PEM 형식으로 변환할 수 있습니다. JKS 파일은 읽기에 JDK 유틸리티가 필요하며 OpenSSL에서 처리할 수 없습니다.

형식 간 변환은 JDK의 keytool 유틸리티를 사용하여 수행됩니다. JKS에서 PKCS12로 마이그레이션할 때 모든 별칭과 비밀번호가 올바르게 전송되었는지 확인하십시오. keytool -importkeystore 명령을 사용하면 형식에 관계없이 한 Keystore의 내용을 다른 Keystore로 가져올 수 있습니다. 변환 후에는 키 버전 간의 혼동을 피하기 위해 이전 JKS 파일을 삭제하는 것이 좋습니다. Android Studio는 서명된 빌드를 생성할 때 두 형식을 모두 지원합니다.

keytool로 Keystore 생성

keytool 유틸리티는 JDK(Java Development Kit)의 일부이며 Keystore를 생성, 보기 및 관리하기 위한 완전한 명령 세트를 제공합니다. 하나의 키 쌍으로 새 Keystore를 생성하려면 PKCS12 형식, RSA 알고리즘, 키 크기 및 인증서 유효 기간을 지정하여 keytool -genkeypair 명령을 사용합니다. Google Play는 최소 25년(9125일)의 인증서 유효 기간을 요구합니다 — -validity 매개변수에 이 값을 지정하는 것이 좋습니다.

새 Keystore 생성

Android 프로젝트를 위한 PKCS12 형식의 Keystore 생성 예제입니다. -dname 매개변수에는 인증서의 X.500 Distinguished Name이 포함됩니다. -ext 매개변수는 필요한 경우 Subject Alternative Name을 포함합니다 — Android의 경우 Basic Constraints로 충분합니다:

# Android용 PKCS12 Keystore 생성
keytool -genkeypair -alias "upload_key" \
  -keyalg RSA -keysize 2048 -validity 9125 \
  -keystore "release-keystore.p12" \
  -storetype PKCS12 \
  -dname "CN=Developer,O=Company,C=RU"

Keytool은 Keystore 비밀번호와 키 비밀번호를 입력하라는 메시지를 표시합니다(일치시킬 수 있음). -storetype PKCS12 매개변수는 최신 형식으로 파일을 생성합니다. -keysize 2048은 최소 RSA 키 크기에 대한 Google의 요구 사항을 충족합니다. -validity 9125(25년)는 애플리케이션의 예상 전체 수명 주기 동안 호환성을 보장합니다. Keystore를 생성한 후 keytool -list -v -keystore release-keystore.p12 명령으로 내용을 확인하는 것이 좋습니다.

Keystore 내용 보기

Keystore 항목을 확인하려면 -list 플래그와 함께 명령을 사용합니다. 출력에는 별칭, 생성 및 만료 날짜, 항목 유형 및 SHA-256 지문이 포함됩니다. Android Studio는 기존 Keystore를 선택할 때 Generate Signed Bundle / APK 대화 상자에서 동일한 정보를 표시합니다:

# Keystore 항목 보기
keytool -list -v -keystore "release-keystore.p12" \
  -storetype PKCS12

CI/CD에서 Keystore 사용

CI/CD 파이프라인에서 Keystore는 안전하게 보관되어야 하며 손상 위험 없이 빌드 에이전트에 전달되어야 합니다. GitHub Actions는 base64 형식으로 바이너리 파일을 저장하기 위한 Secrets를 제공합니다. Keystore는 base64 명령으로 인코딩되고 결과 문자열은 리포지토리 시크릿에 저장되며 빌드 단계에서 다시 파일로 디코딩됩니다. GitLab CI는 File 유형의 Variables를 통해 유사한 메커니즘을 사용합니다.

GitHub Actions에서 Keystore를 사용한 CI 빌드 설정 예제에는 시크릿에서 Keystore 디코딩, Gradle 속성 구성 및 서명된 빌드 실행이 포함됩니다. Gradle의 Android 플러그인은 keystore.properties 파일(로컬 개발을 위해 .gitignore에서 제외) 또는 CI 시스템 환경 변수에서 Keystore 경로와 비밀번호를 읽습니다:

// build.gradle (app) — 서명 구성
@Override
android {
    signingConfigs {
        release {
            storeFile file("release-keystore.p12")
            storePassword System.getenv("STORE_PASSWORD")
            keyAlias System.getenv("KEY_ALIAS")
            keyPassword System.getenv("KEY_PASSWORD")
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

Gradle은 CI 시스템에서 설정한 환경 변수를 읽습니다. Keystore 파일은 storeFile에 지정된 대로 애플리케이션 모듈의 루트에 있어야 합니다. 보안을 위해 리포지토리에 비밀번호를 저장하지 마십시오 — CI 시스템 Secrets를 사용하세요. Android용 Fastlane은 Google Play Console과 작동하는 supply 플러그인을 제공하지만 APK 서명에는 여전히 에이전트의 로컬 Keystore가 필요합니다.

대안은 Google Play App Signing입니다. 이 옵션을 사용하면 개발자는 업로드 키(upload key)만 Google Play에 업로드하고 Google은 자체 키로 최종 APK에 서명합니다. 이 경우 Keystore는 업로드 키를 만드는 데만 사용되며 분실해도 업데이트가 차단되지 않습니다 — 새 업로드 키를 생성하여 Console에 등록할 수 있습니다. Google Play App Signing은 2021년 8월부터 새 애플리케이션에 필수입니다.

Keystore 보안 및 백업

Keystore 분실은 Android 개발에서 가장 중요한 문제 중 하나입니다. 백업 없이는 기존 애플리케이션의 업데이트를 출시할 수 없습니다 — Google Play는 다른 키로 서명된 APK를 거부합니다. Keystore의 백업 복사본을 서로 다른 물리적 또는 클라우드 저장소에 최소 2개 보관하는 것이 좋습니다: 예를 들어 팀의 클라우드 저장소에 암호화된 파일과 조직 금고의 물리적 미디어입니다. Keystore 및 키 비밀번호는 파일과 별도로, 예를 들어 액세스 제어가 있는 비밀번호 관리자에 저장됩니다.

Android Studio는 Generate Signed Bundle / APK 대화 상자에서 새 Keystore를 만들 때 향후 빌드를 위한 경로를 기억하는 옵션을 제공합니다. 그러나 개발 환경 자체는 백업을 생성하지 않습니다 — 이는 개발자의 책임입니다. 팀 개발에서는 모든 팀 구성원에게 안전한 채널을 통해 업로드 키를 전달하는 Google Play App Signing을 사용하는 것이 좋습니다. Gradle은 생성된 debug.keystore로 자동으로 디버그 빌드에 서명할 수 있으며, 이는 백업이 필요하지 않습니다 — 모든 Android Studio 설치에서 동일합니다.

전송 중 Keystore 보안: .p12 또는 .jks 파일은 암호화된 채널(SFTP, HTTPS, 암호화된 이메일 첨부 파일)을 통해서만 전송해야 합니다. Keystore를 소스 코드 리포지토리에 포함하지 마십시오 — 비공개 리포지토리라도 마찬가지입니다. GitGuardian 또는 GitHub secret scanning은 자격 증명 게시를 자동으로 감지하지만 리포지토리에 Keystore를 저장하는 것은 여전히 보안 위반입니다. CI/CD의 경우 인프라 수준 암호화와 함께 플랫폼의 시크릿 메커니즘(GitHub Actions Secrets, GitLab CI Variables, Jenkins Credentials)을 사용하십시오.