Keystore: nedir, hangi biçimler vardır ve nasıl çalışır

Keystore nedir

Keystore (KeyStore), kriptografik anahtarları, sertifikaları ve güvenilir girişleri saklamak için Java Cryptography Architecture (JCA) standardı bir mekanizmadır. Android geliştirmede Keystore, yayınlanmadan önce uygulamayı imzalayan özel anahtarı saklamak için kullanılır. İmza, uygulamanın belirtilen geliştirici tarafından yayınlandığını ve yayınlandıktan sonra kodunun değiştirilmediğini garanti eder. Her uygulama güncellemesi aynı anahtarla imzalanmalıdır, aksi takdirde Google Play APK veya App Bundle'ı reddeder.

Bir Keystore, her biri bir sertifikayla birlikte bir anahtar çiftini (özel ve genel) temsil eden birden çok giriş (takma ad) içerebilir. Takma ad (Alias), imzalama sırasında uygulamanın anahtara eriştiği benzersiz giriş adıdır. Tipik bir Android projesinde Keystore, sürüm sürümünü imzalamak için bir giriş içerir ve hata ayıklama yapılarını imzalamak için ek girişler içerebilir. Google Play Console, yüklenen her uygulama için SHA-1 ve SHA-256 sertifika parmak izlerini görüntüler.

Android Studio, Build → Generate Signed Bundle / APK menüsü aracılığıyla yerleşik Keystore desteği içerir. Android Studio'nun imza sihirbazı, yeni bir Keystore oluşturmanıza veya mevcut birini seçmenize, bir takma ad, Keystore ve anahtar şifreleri ile sertifika verilerini (kuruluş adı, şehir, ülke) belirtmenize olanak tanır. Bu veriler sertifikaya gömülür ve APK imzası doğrulanırken kullanıcılara görünür olur. Google Play, sertifikanın en az 25 yıl geçerli olmasını gerektirir — Android, uygulamayı yüklerken son kullanma tarihini kontrol eder.

Keystore neden Android için önemlidir

Google Play'deki uygulama güncellemeleri yalnızca ilk sürümü imzalayan aynı anahtarla mümkündür. Keystore kaybolursa, güncelleme yayınlamak imkansızdır — uygulamanın farklı bir paket adıyla yeniden yayınlanması gerekir. Google Play Console Help (2026)'ya göre, uygulama imzalama anahtarı yalnızca Google Play App Signing (anahtarı Google tarafında saklayan bir hizmet) aracılığıyla kurtarılabilir. Geliştirici bu seçeneği kullandıysa, yerel Keystore'un kaybı kritik değildir.

Keystore nasıl çalışır

Bir Android uygulamasını imzalama süreci, APK içeriğinin bir özetini (hash) oluşturmayı ve Keystore'daki özel anahtarla şifrelemeyi içerir. Android SDK Build Tools, APK Signature Scheme v2 (veya Android 9+ için v3) kullanarak imzalamayı gerçekleştiren apksigner yardımcı programını içerir. Uygulamayı yüklerken Android imzayı doğrular: imzayı sertifikanın genel anahtarıyla çözer, APK hash'ini orijinaliyle karşılaştırır — hash'ler eşleşmezse yükleme reddedilir.

Android birden çok imza şemasını destekler: v1 (JAR imzalama), v2 (APK Signature Scheme), v3 (anahtar döndürme desteğiyle APK Signature Scheme) ve v4 (Android 11+ için artımlı yüklemeler). Google Play, yeni uygulamalar için v2 veya v3 gerektirir. apksigner, anahtar ilgili algoritmaları destekliyorsa imzalama sırasında gerekli tüm şemaları otomatik olarak ekler. Android 11+, büyük APK'lerin cihaza artımlı olarak yüklenmesini hızlandıran v4 imzayla ADB yüklemesini destekler.

Algoritmalar: Android, imzalama anahtarı için RSA-2048 veya ECDSA P-256 kullanılmasını önerir. Sertifika X.509 v3 olmalıdır. Android, sertifikanın yükleme sırasında geçerli olduğunu doğrular — süresi dolmuşsa yükleme engellenir. Bu nedenle Google, sertifikanın geçerlilik süresinin en az 25 yıl olarak ayarlanmasını önerir. Google Play App Signing iki anahtar kullanır: uygulama imzalama anahtarı (app signing key) ve yükleme anahtarı (upload key) — geliştirici APK'yı Console'a yüklemek için yükleme anahtarını kullanır ve Google, kullanıcılar için uygulamayı ana anahtarla imzalar.

Keystore biçimleri: JKS ve PKCS12

Java iki ana Keystore biçimini destekler: JKS (Java KeyStore) — JDK 1.2'den beri var olan Oracle'ın tescilli biçimi ve PKCS12 — RSA Laboratories'in standartlaştırılmış Public-Key Cryptography Standards #12 biçimi. JKS kendi veri depolama biçimini kullanır ve yalnızca Java ekosistemi içinde desteklenir. PKCS12, Java, .NET, OpenSSL, Python (cryptography) ve diğer çoğu kriptografik kitaplık tarafından desteklenen açık bir standarttır.

Google Play, 2021'den sonra oluşturulan yeni Keystore'lar için PKCS12'yi tercih edilen biçim olarak önerir. JDK 9 ve sonrası, varsayılan olarak PKCS12 biçiminde Keystore'lar oluşturur (önceden varsayılan JKS idi). PKCS12'nin ana avantajı uyumluluktur: bir .p12 dosyası Java'ya bağlı olmayan herhangi bir ortamda açılabilir. OpenSSL, PKCS12'den sertifikaları çıkarabilir ve PEM biçimine dönüştürebilir. JKS dosyaları okumak için JDK yardımcı programları gerektirir ve OpenSSL tarafından işlenemez.

Biçimler arasındaki dönüşüm, JDK'daki keytool yardımcı programı kullanılarak yapılır. JKS'den PKCS12'ye geçiş yaparken tüm takma adların ve şifrelerin doğru şekilde aktarıldığından emin olun. keytool -importkeystore komutu, biçimden bağımsız olarak bir Keystore'un içeriğini diğerine aktarmaya olanak tanır. Dönüşümden sonra, anahtar sürümleriyle karışıklığı önlemek için eski JKS dosyasını silmek en iyisidir. Android Studio, imzalı bir yapı oluştururken her iki biçimi de destekler.

Keytool ile Keystore oluşturma

keytool yardımcı programı JDK'nin (Java Development Kit) bir parçasıdır ve Keystore'ları oluşturmak, görüntülemek ve yönetmek için eksiksiz bir komut seti sağlar. Bir anahtar çiftiyle yeni bir Keystore oluşturmak için, PKCS12 biçimini, RSA algoritmasını, anahtar boyutunu ve sertifika geçerlilik süresini belirterek keytool -genkeypair komutu kullanılır. Google Play, en az 25 yıl (9125 gün) sertifika geçerliliği gerektirir — bu değerin -validity parametresinde belirtilmesi önerilir.

Yeni bir Keystore oluşturma

Bir Android projesi için PKCS12 biçiminde Keystore oluşturma örneği. -dname parametresi, sertifikanın X.500 Distinguished Name'ini içerir. -ext parametresi, gerekirse Subject Alternative Name'ı ekler — Android için Basic Constraints yeterlidir:

# Android için PKCS12 Keystore oluşturma
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 şifresini ve anahtar şifresini isteyecektir (aynı olabilirler). -storetype PKCS12 parametresi, modern biçimde bir dosya oluşturur. -keysize 2048, Google'ın minimum RSA anahtar boyutu gereksinimlerini karşılar. -validity 9125 (25 yıl), uygulamanın beklenen tüm yaşam döngüsü boyunca uyumluluğu garanti eder. Keystore'u oluşturduktan sonra, içeriğini keytool -list -v -keystore release-keystore.p12 komutuyla doğrulamanız önerilir.

Keystore içeriğini görüntüleme

Keystore girişlerini kontrol etmek için -list işaretiyle komut kullanılır. Çıktı, takma adı, oluşturma ve son kullanma tarihlerini, giriş türünü ve SHA-256 parmak izlerini içerir. Android Studio, mevcut bir Keystore seçerken Generate Signed Bundle / APK iletişim kutusunda aynı bilgileri görüntüler:

# Keystore girişlerini görüntüleme
keytool -list -v -keystore "release-keystore.p12" \
  -storetype PKCS12

CI/CD'de Keystore kullanımı

Bir CI/CD hattında, Keystore güvenli bir şekilde saklanmalı ve tehlikeye atılma riski olmadan derleme aracısına iletilmelidir. GitHub Actions, ikili dosyaları base64 biçiminde saklamak için Secrets sağlar. Keystore, base64 komutuyla kodlanır, elde edilen dize depo sırlarında saklanır ve derleme aşamasında tekrar bir dosyaya dönüştürülür. GitLab CI, File türündeki Variables aracılığıyla benzer bir mekanizma kullanır.

GitHub Actions'da Keystore ile bir CI derlemesi kurma örneği, bir sırdan Keystore'un kodunu çözmeyi, Gradle özelliklerini yapılandırmayı ve imzalı bir derleme yürütmeyi içerir. Gradle Android eklentisi, keystore.properties dosyasından (yerel geliştirme için .gitignore'dan hariç tutulur) veya CI sistemi ortam değişkenlerinden Keystore yolunu ve şifrelerini okur:

// build.gradle (app) — imza yapılandırması
@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 sistemi tarafından ayarlanan ortam değişkenlerini okur. Keystore dosyası, storeFile'da belirtildiği gibi uygulama modülünün kökünde bulunmalıdır. Güvenlik için, depoda asla şifre saklamayın — CI sistemi Secrets'ını kullanın. Android için Fastlane, Google Play Console ile çalışan supply eklentisini sağlar, ancak APK imzalaması yine de aracıda yerel bir Keystore gerektirir.

Bir alternatif Google Play App Signing'dir. Bu seçeneği kullanırken, geliştirici yalnızca yükleme anahtarını (upload key) Google Play'e yükler ve Google, nihai APK'yı kendi anahtarıyla imzalar. Bu durumda, Keystore yalnızca yükleme anahtarını oluşturmak için kullanılır ve kaybı güncellemeleri engellemez — yeni bir yükleme anahtarı oluşturulabilir ve Console'a kaydedilebilir. Google Play App Signing, Ağustos 2021'den itibaren yeni uygulamalar için zorunludur.

Keystore güvenliği ve yedekleme

Bir Keystore'u kaybetmek, Android geliştirmedeki en kritik sorunlardan biridir. Yedek olmadan, mevcut bir uygulamanın güncellemesini yayınlamak imkansızdır — Google Play, farklı bir anahtarla imzalanmış APK'leri reddeder. Keystore'un en az iki yedek kopyasının farklı fiziksel veya bulut depolama alanlarında saklanması önerilir: örneğin, ekibin bulut depolamasında şifrelenmiş bir dosya ve kuruluş kasasında fiziksel bir ortam. Keystore ve anahtar şifreleri, dosyadan ayrı olarak, örneğin erişim kontrollü bir parola yöneticisinde saklanır.

Android Studio, Generate Signed Bundle / APK iletişim kutusunda yeni bir Keystore oluştururken, gelecekteki derlemeler için yolları hatırlamayı teklif eder. Ancak geliştirme ortamının kendisi bir yedek oluşturmaz — bu geliştiricinin sorumluluğundadır. Ekip geliştirmesi için, yükleme anahtarının güvenli bir kanal aracılığıyla tüm ekip üyelerine iletilmesiyle Google Play App Signing kullanılması önerilir. Gradle, oluşturulan debug.keystore ile hata ayıklama yapılarını otomatik olarak imzalayabilir, bu yedekleme gerektirmez — tüm Android Studio yüklemeleri için aynıdır.

Aktarım sırasında Keystore güvenliği: .p12 veya .jks dosyaları yalnızca şifrelenmiş kanallar (SFTP, HTTPS, şifrelenmiş e-posta ekleri) aracılığıyla aktarılmalıdır. Keystore'u asla kaynak kodu deposuna dahil etmeyin — özel olsa bile. GitGuardian veya GitHub secret scanning, kimlik bilgisi yayınını otomatik olarak algılar, ancak Keystore'u bir depoda saklamak yine de bir güvenlik ihlalidir. CI/CD için, altyapı düzeyinde şifrelemeyle birlikte platformun gizli mekanizmasını (GitHub Actions Secrets, GitLab CI Variables, Jenkins Credentials) kullanın.