Keystore: istota, jakie są formaty i jak działa

Co to jest Keystore

Keystore (KeyStore) — to standardowy mechanizm Java Cryptography Architecture (JCA) do przechowywania kluczy kryptograficznych, certyfikatów i zaufanych wpisów. W programowaniu Androida Keystore jest używany do przechowywania klucza prywatnego, którym podpisywana jest aplikacja przed publikacją. Podpis gwarantuje, że aplikacja została rzeczywiście wydana przez określonego dewelopera, a jej kod nie został zmodyfikowany po publikacji. Każda aktualizacja aplikacji musi być podpisana tym samym kluczem, w przeciwnym razie Google Play odrzuci plik APK lub App Bundle.

Keystore może zawierać wiele wpisów (aliasów), z których każdy reprezentuje parę kluczy (prywatny i publiczny) wraz z certyfikatem. Alias — unikalna nazwa wpisu, pod którą aplikacja odwołuje się do klucza podczas podpisywania. W typowym projekcie Android Keystore zawiera jeden wpis do podpisywania wersji wydaniowej i może zawierać dodatkowe do podpisywania kompilacji debugowych. Google Play Console wyświetla odciski SHA-1 i SHA-256 certyfikatu dla każdej przesłanej aplikacji.

Android Studio zawiera wbudowaną obsługę Keystore poprzez menu Build → Generate Signed Bundle / APK. Kreator podpisywania Android Studio umożliwia utworzenie nowego Keystore lub wybór istniejącego, określenie aliasu, haseł Keystore i klucza, a także danych certyfikacyjnych (nazwa organizacji, miasto, kraj). Dane te są osadzane w certyfikacie i widoczne dla użytkowników podczas weryfikacji podpisu APK. Google Play wymaga, aby ważność certyfikatu wynosiła co najmniej 25 lat — Android sprawdza datę wygaśnięcia podczas instalacji aplikacji.

Dlaczego Keystore jest ważny dla Androida

Aktualizacja aplikacji w Google Play jest możliwa tylko tym samym kluczem, którym podpisana została pierwsza wersja. Jeśli Keystore zostanie utracony, nie można opublikować aktualizacji — aplikację trzeba będzie wydać ponownie pod nową nazwą pakietu (package name). Według Google Play Console Help (2026), klucz podpisu aplikacji można odzyskać tylko poprzez Google Play App Signing — usługę, która przechowuje klucz po stronie Google. Jeśli deweloper skorzystał z tej opcji, utrata lokalnego Keystore nie jest krytyczna.

Jak działa Keystore

Proces podpisywania aplikacji Android obejmuje utworzenie skrótu (haszu) zawartości APK i jego zaszyfrowanie kluczem prywatnym z Keystore. Android SDK Build Tools zawierają narzędzie apksigner, które wykonuje podpis w formacie APK Signature Scheme v2 (lub v3 dla Android 9+). Podczas instalacji aplikacji Android weryfikuje podpis: odszyfrowuje podpis kluczem publicznym certyfikatu, porównuje hasz APK z oryginałem — jeśli hasze nie są zgodne, instalacja jest odrzucana.

Android obsługuje kilka schematów podpisu: v1 (JAR signing), v2 (APK Signature Scheme), v3 (APK Signature Scheme z obsługą rotacji kluczy) i v4 (instalacje przyrostowe Android 11+). Google Play wymaga v2 lub v3 dla nowych aplikacji. apksigner automatycznie dodaje wszystkie niezbędne schematy podczas podpisywania, jeśli klucz obsługuje odpowiednie algorytmy. Android 11+ obsługuje instalację ADB z podpisem v4, co przyspiesza przyrostowe ładowanie dużych plików APK na urządzenie.

Algorytmy: Android zaleca używanie RSA-2048 lub ECDSA P-256 dla klucza podpisu. Certyfikat powinien być X.509 v3. Android sprawdza, czy certyfikat jest ważny w momencie instalacji — jeśli wygasł, instalacja jest blokowana. Dlatego Google zaleca ustawienie okresu ważności certyfikatu na co najmniej 25 lat. Google Play App Signing używa dwóch kluczy: klucza aplikacji (app signing key) i klucza przesyłania (upload key) — klucz przesyłania jest używany przez dewelopera do przesyłania APK do Console, a Google podpisuje aplikację dla użytkowników głównym kluczem.

Formaty Keystore: JKS i PKCS12

Java obsługuje dwa główne formaty Keystore: JKS (Java KeyStore) — zastrzeżony format Oracle, istniejący od JDK 1.2, oraz PKCS12 — ustandaryzowany format Public-Key Cryptography Standards #12 firmy RSA Laboratories. JKS używa własnego formatu przechowywania danych i jest obsługiwany tylko w ekosystemie Java. PKCS12 to otwarty standard obsługiwany przez Java, .NET, OpenSSL, Python (cryptography) i większość innych bibliotek kryptograficznych.

Google Play zaleca PKCS12 jako preferowany format dla nowych Keystore tworzonych po 2021 roku. JDK 9 i nowsze domyślnie tworzą Keystore w formacie PKCS12 (wcześniej domyślnym był JKS). Główną zaletą PKCS12 jest kompatybilność: plik .p12 można otworzyć w dowolnym środowisku niezwiązanym z Java. OpenSSL może wyodrębniać certyfikaty z PKCS12 i konwertować je do formatu PEM. Pliki JKS wymagają narzędzi JDK do odczytu i nie mogą być przetwarzane przez OpenSSL.

Konwersja między formatami odbywa się za pomocą narzędzia keytool z JDK. Podczas migracji z JKS na PKCS12 należy upewnić się, że wszystkie aliasy i hasła zostały poprawnie przeniesione. Polecenie keytool -importkeystore umożliwia zaimportowanie zawartości jednego Keystore do drugiego niezależnie od formatu. Po konwersji stary plik JKS lepiej usunąć, aby uniknąć pomyłek z wersjami klucza. Android Studio obsługuje oba formaty podczas generowania podpisanej kompilacji.

Tworzenie Keystore za pomocą keytool

Narzędzie keytool wchodzi w skład JDK (Java Development Kit) i udostępnia pełny zestaw poleceń do tworzenia, przeglądania i zarządzania Keystore. Do utworzenia nowego Keystore z jedną parą kluczy używa się polecenia keytool -genkeypair z określeniem formatu PKCS12, algorytmu RSA, rozmiaru klucza i okresu ważności certyfikatu. Google Play wymaga ważności certyfikatu co najmniej 25 lat (9125 dni) — tę wartość zaleca się podać w parametrze -validity.

Tworzenie nowego Keystore

Przykład generacji Keystore w formacie PKCS12 dla projektu Android. Parametr -dname zawiera X.500 Distinguished Name certyfikatu. Parametr -ext włączy Subject Alternative Name, jeśli jest wymagany — dla Androida wystarczą Basic Constraints:

# Tworzenie PKCS12 Keystore dla Androida
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 poprosi o hasło Keystore i hasło klucza (mogą być takie same). Parametr -storetype PKCS12 tworzy plik w nowoczesnym formacie. -keysize 2048 odpowiada wymaganiom Google dotyczącym minimalnego rozmiaru klucza RSA. -validity 9125 (25 lat) zapewnia kompatybilność na cały spodziewany cykl życia aplikacji. Po utworzeniu Keystore zaleca się sprawdzenie jego zawartości poleceniem keytool -list -v -keystore release-keystore.p12.

Przeglądanie zawartości Keystore

Do sprawdzenia wpisów Keystore używa się polecenia z flagą -list. Wynik zawiera alias, daty utworzenia i wygaśnięcia, typ wpisu oraz odciski SHA-256. Android Studio wyświetla te same informacje w oknie Generate Signed Bundle / APK przy wyborze istniejącego Keystore:

# Przeglądanie wpisów Keystore
keytool -list -v -keystore "release-keystore.p12" \
  -storetype PKCS12

Używanie Keystore w CI/CD

W potoku CI/CD Keystore musi być przechowywany w bezpieczny sposób i przekazywany do agenta kompilacji bez ryzyka naruszenia bezpieczeństwa. GitHub Actions udostępnia Secrets do przechowywania plików binarnych w formacie base64. Keystore jest kodowany poleceniem base64, uzyskany ciąg jest przechowywany w sekretach repozytorium, a na etapie kompilacji jest dekodowany z powrotem do pliku. GitLab CI używa podobnego mechanizmu poprzez Variables z typem File.

Przykład konfiguracji kompilacji CI z Keystore w GitHub Actions obejmuje dekodowanie Keystore z sekretu, konfigurację właściwości Gradle i wykonanie podpisanej kompilacji. Gradle wtyczki Android odczytuje ścieżkę do Keystore i hasła z pliku keystore.properties (wyłączonego z .gitignore do lokalnego rozwoju) lub ze zmiennych środowiskowych systemu CI:

// build.gradle (app) — konfiguracja podpisu
@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 odczytuje zmienne środowiskowe ustawione przez system CI. Plik Keystore powinien znajdować się w katalogu głównym modułu aplikacji, jak określono w storeFile. Dla bezpieczeństwa nigdy nie przechowuj haseł w repozytorium — używaj Secrets systemu CI. Fastlane dla Androida udostępnia wtyczkę supply, która współpracuje z Google Play Console, ale podpisywanie APK i tak wymaga lokalnego Keystore na agencie.

Alternatywą jest Google Play App Signing. Przy użyciu tej opcji deweloper przesyła do Google Play tylko klucz przesyłania (upload key), a Google podpisuje końcowy APK swoim kluczem. W tym przypadku Keystore jest używany tylko do utworzenia klucza przesyłania, a jego utrata nie blokuje aktualizacji — można wygenerować nowy upload key i zarejestrować go w Console. Google Play App Signing jest obowiązkowy dla nowych aplikacji od sierpnia 2021 roku.

Bezpieczeństwo i kopia zapasowa Keystore

Utrata Keystore to jeden z najbardziej krytycznych problemów w programowaniu Androida. Bez kopii zapasowej Keystore nie można wydać aktualizacji istniejącej aplikacji — Google Play odrzuca APK podpisany innym kluczem. Zaleca się przechowywanie co najmniej dwóch kopii zapasowych Keystore w różnych fizycznych lub chmurowych magazynach: na przykład zaszyfrowany plik w chmurze zespołu i nośnik fizyczny w sejfie organizacji. Hasła Keystore i klucza są przechowywane oddzielnie od pliku, na przykład w menedżerze haseł z kontrolą dostępu.

Android Studio przy tworzeniu nowego Keystore w oknie Generate Signed Bundle / APK oferuje zapamiętanie ścieżek do przyszłych kompilacji. Jednak samo środowisko programistyczne nie tworzy kopii zapasowej — to odpowiedzialność dewelopera. W przypadku pracy zespołowej zaleca się używanie Google Play App Signing z przekazaniem upload key przez bezpieczny kanał wszystkim członkom zespołu. Gradle umożliwia podpisywanie kompilacji debugowych automatycznie wygenerowanym debug.keystore, który nie wymaga tworzenia kopii zapasowej — jest taki sam dla wszystkich instalacji Android Studio.

Bezpieczeństwo Keystore podczas przesyłania: plik .p12 lub .jks powinien być przesyłany tylko przez zaszyfrowane kanały (SFTP, HTTPS, zaszyfrowane załączniki email). Nigdy nie umieszczaj Keystore w repozytorium kodu źródłowego — nawet prywatnym. GitGuardian lub GitHub secret scanning automatycznie wykrywają publikację danych uwierzytelniających, ale przechowywanie Keystore w repozytorium nadal stanowi naruszenie bezpieczeństwa. W CI/CD używaj mechanizmu sekretów platformy (GitHub Actions Secrets, GitLab CI Variables, Jenkins Credentials) z szyfrowaniem na poziomie infrastruktury.